### Example output Source: https://pkg.go.dev/github.com/mroth/weightedrand The expected output from the weighted random selection example. ```text Output: 🥑 ``` -------------------------------- ### Perform weighted random selection Source: https://pkg.go.dev/github.com/mroth/weightedrand Demonstrates initializing a Chooser with weighted items and picking a random result. ```go import ( /* ...snip... */ wr "github.com/mroth/weightedrand" ) func main() { rand.Seed(time.Now().UTC().UnixNano()) // always seed random! chooser, _ := wr.NewChooser( wr.Choice{Item: "🍒", Weight: 0}, wr.Choice{Item: "🍋", Weight: 1}, wr.Choice{Item: "🍊", Weight: 1}, wr.Choice{Item: "🍉", Weight: 3}, wr.Choice{Item: "🥑", Weight: 5}, ) /* The following will print 🍋 and 🍊 with 0.1 probability, 🍉 with 0.3 probability, and 🥑 with 0.5 probability. 🍒 will never be printed. (Note the weights don't have to add up to 10, that was just done here to make the example easier to read.) */ result := chooser.Pick().(string) fmt.Println(result) } ``` -------------------------------- ### Create a new Choice Source: https://pkg.go.dev/github.com/mroth/weightedrand Helper function to instantiate a Choice. ```go func NewChoice(item interface{}, weight uint) Choice ``` -------------------------------- ### weightedrand - Fast weighted random selection for Go Source: https://pkg.go.dev/github.com/mroth/weightedrand The weightedrand package provides a way to randomly select elements from a list with non-equal probabilities, defined by relative weights. It is optimized for repeated selections, offering significant performance benefits over single-operation selection methods for large datasets. ```APIDOC ## Package weightedrand ### Description Fast weighted random selection for Go. Randomly selects an element from some kind of list, where the chances of each element to be selected are not equal, but rather defined by relative "weights" (or probabilities). This is called weighted random selection. ### Usage ```go import ( /* ...snip... */ wr "github.com/mroth/weightedrand" ) func main() { rand.Seed(time.Now().UTC().UnixNano()) // always seed random! chooser, _ := wr.NewChooser( wr.Choice{Item: "🍒", Weight: 0}, wr.Choice{Item: "🍋", Weight: 1}, wr.Choice{Item: "🍊", Weight: 1}, wr.Choice{Item: "🍉", Weight: 3}, wr.Choice{Item: "🥑", Weight: 5}, ) /* The following will print 🍋 and 🍊 with 0.1 probability, 🍉 with 0.3 probability, and 🥑 with 0.5 probability. 🍒 will never be printed. (Note the weights don't have to add up to 10, that was just done here to make the example easier to read.) */ result := chooser.Pick().(string) fmt.Println(result) } ``` ### Performance Comparison Compares `weightedrand` with `github.com/jmcvetta/randutil` for repeated selections. `weightedrand` is significantly faster for large datasets due to its presorted cache optimized for binary search. | Num choices | `randutil` | `weightedrand` | `weightedrand -cpu=8`* | |---|---|---|---| | 10 | 201 ns/op | 38 ns/op | 2.9 ns/op | | 100 | 267 ns/op | 51 ns/op | 4.1 ns/op | | 1,000 | 1012 ns/op | 67 ns/op | 5.4 ns/op | | 10,000 | 8683 ns/op | 83 ns/op | 6.9 ns/op | | 100,000 | 123500 ns/op | 105 ns/op | 12.0 ns/op | | 1,000,000 | 2399614 ns/op | 218 ns/op | 17.2 ns/op | | 10,000,000 | 26804440 ns/op | 432 ns/op | 35.1 ns/op | *_: Since `v0.3.0` weightedrand can efficiently utilize a single Chooser across multiple CPU cores in parallel, making it even faster in overall throughput. See PR#2 for details. Informal benchmarks conducted on an Intel Xeon W-2140B CPU (8 core @ 3.2GHz, hyperthreading enabled)._ Note: If you are only picking from the same distribution once, `randutil` might be faster. `weightedrand` optimizes for repeated calls at the expense of some initialization time and memory storage. ### Credits Algorithm details can be found in: Weighted random generation in Python. ### Types #### type Choice ```go type Choice struct { Item interface{} Weight uint } ``` Choice is a generic wrapper that can be used to add weights for any item. #### func NewChoice ```go func NewChoice(item interface{}, weight uint) Choice ``` NewChoice creates a new Choice with specified item and weight. #### type Chooser ```go type Chooser struct { // contains filtered or unexported fields } ``` ### Functions #### func NewChooser ```go func NewChooser(choices ...Choice) (*Chooser, error) ``` NewChooser creates a new Chooser from a list of choices. It returns an error if the choices are invalid. #### func (Chooser) Pick ```go func (c Chooser) Pick() interface{} ``` Pick randomly selects and returns an item from the chooser based on the defined weights. #### func (Chooser) PickSource ```go func (c Chooser) PickSource(rs *rand.Rand) interface{} ``` PickSource randomly selects and returns an item from the chooser using a provided `rand.Rand` source. ``` -------------------------------- ### NewChooser Function Source: https://pkg.go.dev/github.com/mroth/weightedrand Initializes a new Chooser for picking from the provided choices. Ensure choices are valid before initialization. ```go func NewChooser(choices ...Choice) (*Chooser, error) ``` -------------------------------- ### NewChooser Source: https://pkg.go.dev/github.com/mroth/weightedrand Initializes a new Chooser instance for picking from provided choices. ```APIDOC ## func NewChooser ### Description Initializes a new Chooser for picking from the provided choices. ### Signature `func NewChooser(choices ...Choice) (*Chooser, error)` ``` -------------------------------- ### Define a Choice struct Source: https://pkg.go.dev/github.com/mroth/weightedrand The structure used to associate an item with a weight. ```go type Choice struct { Item interface{} Weight uint } ``` -------------------------------- ### Chooser.Pick Method Source: https://pkg.go.dev/github.com/mroth/weightedrand Returns a single weighted random Choice.Item from the Chooser using the global random source. Suitable for single-threaded or low-contention scenarios. ```go func (c Chooser) Pick() interface{} ``` -------------------------------- ### Chooser.PickSource Method Source: https://pkg.go.dev/github.com/mroth/weightedrand Returns a single weighted random Choice.Item from the Chooser, utilizing a provided *rand.Rand source. Use this to avoid global random source contention in high-throughput concurrent applications. The caller is responsible for ensuring the provided rand.Source is thread-safe. ```go func (c Chooser) PickSource(rs *rand.Rand) interface{} ``` -------------------------------- ### Chooser.Pick Source: https://pkg.go.dev/github.com/mroth/weightedrand Returns a single weighted random item using the global random source. ```APIDOC ## func (Chooser) Pick ### Description Pick returns a single weighted random Choice.Item from the Chooser. Utilizes global rand as the source of randomness. ### Signature `func (c Chooser) Pick() interface{}` ``` -------------------------------- ### Chooser.PickSource Source: https://pkg.go.dev/github.com/mroth/weightedrand Returns a single weighted random item using a provided random source to avoid lock contention. ```APIDOC ## func (Chooser) PickSource ### Description PickSource returns a single weighted random Choice.Item from the Chooser, utilizing the provided *rand.Rand source rs for randomness. This is useful for avoiding lock contention in high-throughput scenarios. ### Signature `func (c Chooser) PickSource(rs *rand.Rand) interface{}` ``` -------------------------------- ### Chooser Struct Definition Source: https://pkg.go.dev/github.com/mroth/weightedrand Defines the Chooser struct, which caches choices for efficient weighted random selection. ```go type Chooser struct { // contains filtered or unexported fields } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.