weightedrand

The weightedrand library is optimized for repeated selections from the same set of choices. It achieves this by creating a presorted cache that allows for fast binary search selection.

When to use weightedrand vs randutil

• Use weightedrand when you need to perform many repeated samplings from a large collection. It is significantly faster for repeated calls but incurs higher initialization time and memory usage.
• Use github.com/jmcvetta/randutil if you are only performing a single selection from a distribution. It is optimized for the single-operation case.

Parallelism

Starting from v0.3.0, weightedrand can efficiently utilize a single Chooser across multiple CPU cores in parallel, increasing overall throughput for high-concurrency workloads.

To use weightedrand v3, your environment must meet the following requirement:

• Go version: 1.22 or greater.

If you are using an older version of Go, you must use weightedrand v2 instead.

The following errors are returned by NewChooser to prevent unsafe runtime states or imbalanced distributions.

var (
	// If the sum of provided Choice weights exceed the maximum integer value
	// for the current platform, then the internal running total will overflow.
	errWeightOverflow = errors.New("sum of Choice Weights exceeds max int")

	// If there are no Choices available to the Chooser with a weight >= 1,
	// there are no valid choices and Pick would produce a runtime panic.
	errNoValidChoices = errors.New("zero Choices with Weight >= 1")
)

The NewChooser function initializes a Chooser optimized for repeated weighted random selections. It sorts the provided choices by weight and builds a prefix sum array (totals) to enable efficient binary search during selection.

Errors:

• errWeightOverflow: Returned if the sum of all weights exceeds math.MaxUint64.
• errNoValidChoices: Returned if no choices have a weight $\ge 1$.

choices := []weightedrand.Choice[string, int]{
	weightedrand.NewChoice("apple", 10),
	weightedrand.NewChoice("banana", 20),
	weightedrand.NewChoice("cherry", 70),
}

chooser, err := weightedrand.NewChooser(choices...)
if err != nil {
	// handle error
}

The PickWith method allows you to provide a specific *rand.Rand source for randomness. This is useful for reproducible results (e.g., using a seeded source) or when you want to manage your own randomness source.

// Using a custom source
src := rand.New(rand.NewPCG(1, 2))
item := chooser.PickWith(src)

Use NewChoice to wrap an item of any type T with a weight of type W (where W is any integer type). This Choice struct is the building block for the Chooser.

choice := weightedrand.NewChoice("apple", 10)

The Pick method returns a single Item from the Chooser based on the defined weights. It uses the global math/rand/v2 source, which is safe for concurrent usage.

item := chooser.Pick()
fmt.Println(item) // e.g., "cherry"