Weightedrand

https://pkg.go.dev/github.com/mroth/weightedrand@v3.0.0
Admin
Weightedrand is a fast weighted random selection library for Go that efficiently selects items from...
Tokens:2,057
Snippets:22
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### 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
}
```
Tokens:
Raw