weightedoption

README

weightedoption

A Go package for weighted random option selection

Example Usage

package main

import (
	"fmt"
	"log"

	"github.com/eljamo/weightedoption/v2"
)

// Simulates 100 chances for dropping a raid exotic weapon from Destiny, which has a 5% drop chance when a player completes the raid
func main() {
	// Create a new selector with options and their weights
	s, err := weightedoption.NewSelector(
		weightedoption.NewOption('🔫', 5),  // 5% chance for the exotic weapon
		weightedoption.NewOption('❌', 95), // 95% chance for no drop
	)
	if err != nil {
		log.Fatal(err)
	}

	chances := make([]rune, 100) // Array to store the results of 100 attempts
	for i := 0; i < len(chances); i++ {
		chances[i] = s.Select() // Select an option based on their weights
	}
	fmt.Println(string(chances))

	tally := make(map[rune]int)
	for _, c := range chances {
		tally[c]++
	}

	_, err = fmt.Printf("\n🔫: %d\t❌ %d\n", tally['🔫'], tally['❌'])
	if err != nil {
		log.Fatal(err)
	}
}

go run ./example/example.go
❌❌❌❌❌❌❌❌❌❌❌❌🔫❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌🔫❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌❌🔫❌❌❌❌❌❌❌❌❌❌❌❌

🔫: 3	❌ 97

Contributing

If you'd like to contribute, please fork the repository and work your magic. Open a pull request to the main branch if it is a bugfix or feature branch. If it is a hotfix branch, open a pull request to the respective release branch.

Run the tests

go test --race --shuffle on ./...

Run the example

go run ./example/example.go

Branching Strategy

• bugfix/*
• feature/*
• main
• release/v*
• hotfix/*

Workflow Breakdown

• feature and bugfix branches:

  • feature Branches: Create these for new features you are developing.
  • bugfix Branches: Create these for fixing bugs identified in the main branch.
  • Once the feature or fix is complete, merge these branches back into the main branch.

• main branch:

  • The main branch serves as the central integration branch where all feature and bugfix branches are merged.

• release branch:

  • When you are ready to make a release, create a release branch from the main branch.
  • Perform any final testing and adjustments on the release branch.
  • Once the release is stable, it can be deployed from this branch.

• hotfix branch:

  • If a critical issue is found after the release, create a hotfix branch from the release branch.
  • Fix the issue on the hotfix branch and then merge it back into both the release and main branches if applicable.
  • This ensures that the fix is included in the current release(s) and the main branch.

Example Scenarios

• Developing a feature:

  1. Create a feature branch from main.
  2. Develop and test the feature on the feature branch.
  3. Merge the feature branch into main.

• Fixing a bug:

  1. Create a bugfix branch from main.
  2. Fix and test the bug on the bugfix branch.
  3. Merge the bugfix branch into main.

• Making a release:

  1. Create a release branch from main or another release branch.
  2. Perform testing on release branch.
  3. Deploy the release branch.

• Applying a hotfix:

  1. Create a hotfix branch from a release branch.
  2. Fix the critical issue on hotfix branch.
  3. Merge hotfix branch into the release and main branches.

Documentation

Index

• Variables
• type Option
  • func NewOption[DataType any, WeightIntegerType WeightIntegerConstraint](data DataType, weight WeightIntegerType) Option[DataType, WeightIntegerType]
• type Selector
  • func NewSelector[DataType any, WeightIntegerType WeightIntegerConstraint](options ...Option[DataType, WeightIntegerType]) (*Selector[DataType, WeightIntegerType], error)
  • func (s Selector[DataType, WeightIntegerType]) Select() DataType
• type WeightIntegerConstraint

Variables

var (
	// ErrNoValidOptions is used and returned when no Options are found with a Weight >= 1.
	ErrNoValidOptions = errors.New("no Options found with Weight >= 1")
	// ErrWeightOverflow is used and returned when the sum of all Option weights exceeds the max integer value for this system's architecture.
	ErrWeightOverflow = errors.New("Option weight exceeds max integer value for this system's architecture")
)

Types

type Option

type Option[DataType any, WeightIntegerType WeightIntegerConstraint] struct {
	Data   DataType
	Weight WeightIntegerType
}

Option is a struct that holds a data value and its associated weight.

func NewOption

func NewOption[DataType any, WeightIntegerType WeightIntegerConstraint](
	data DataType,
	weight WeightIntegerType,
) Option[DataType, WeightIntegerType]

NewOption creates a new Option with the provided data and weight.

type Selector

type Selector[DataType any, WeightIntegerType WeightIntegerConstraint] struct {
	// contains filtered or unexported fields
}

Selector is a struct that holds a slice of Options, their running total weights, and the total weight.

func NewSelector

func NewSelector[DataType any, WeightIntegerType WeightIntegerConstraint](
	options ...Option[DataType, WeightIntegerType],
) (*Selector[DataType, WeightIntegerType], error)

NewSelector creates a new Selector for selecting provided Options.

func (Selector[DataType, WeightIntegerType]) Select

func (s Selector[DataType, WeightIntegerType]) Select() DataType

Select returns a single Option.Data from Selector.options

type WeightIntegerConstraint

type WeightIntegerConstraint interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr
}

WeightIntegerConstraint is a type constraint for the Weight field of the Option struct.