math

Documentation

Overview

Package math implements dice expression mathematics and functions.

When evaluating an expression with Expression, the package follows order of operations:

All dice notations/expressions are rolled and expanded,
Parenthesis (deepest first),
Functions,
Exponentiation,
Multiplication, division, and modulus from left to right,
Addition and subtraction from left to right

The math package currently relies heavily on https://github.com/Knetic/govaluate.

Benchmarks

The benchmarks for the math package's functions use math/rand as the random byte source rather than crypto/rand in order to limit slowness attributed to sourcing entropy.

Index

• Variables
• func ListDiceFunctions() []string
• func ParseExpressionWithFunc(ctx context.Context, regexp *regexp.Regexp, expression string, ...) (string, error)
• type ExpressionResult
  • func EvaluateExpression(ctx context.Context, expression string) (*ExpressionResult, error)
  • func (de *ExpressionResult) GoString() string
  • func (de *ExpressionResult) String() string

Variables

var (
	ErrNotEnoughArgs   = errors.New("not enough args")
	ErrInvalidArgCount = errors.New("invalid argument count")
)

Possible error types for mathematical functions.

var (
	ErrNilExpression = errors.New("nil expression")
	ErrNilResult     = errors.New("nil result")
)

Math package errors.

var DiceFunctions = map[string]eval.ExpressionFunction{
	"abs":   absExpressionFunction,
	"ceil":  ceilExpressionFunction,
	"floor": floorExpressionFunction,
	"max":   maxExpressionFunction,
	"min":   minExpressionFunction,
	"round": roundExpressionFunction,
}

DiceFunctions are functions usable in dice arithmetic operations, such as round, min, and max.

Functions

func ListDiceFunctions

func ListDiceFunctions() []string

func ParseExpressionWithFunc

func ParseExpressionWithFunc(ctx context.Context, regexp *regexp.Regexp, expression string, repl func([]byte) []byte) (string, error)

ParseExpressionWithFunc

rolledBytes, err := ParseExpressionWithFunc(ctx, dice.DiceWithModifiersExpressionRegex, de.Original, )

Types

type ExpressionResult

type ExpressionResult struct {
	// Original is the original expression input.
	Original string `json:"original"`

	// Rolled is the original expression but with any dice expressions rolled
	// and expanded.
	Rolled string `json:"rolled"`

	// Result is the expression's evaluated total.
	Result float64 `json:"result"`

	// Dice is the list of dice groups rolled as part of the expression. As dice
	// are rolled, their GroupProperties are retrieved.
	Dice []*dice.RollerGroup `json:"dice,omitempty"`
}

An ExpressionResult is a representation of a dice roll that has been evaluated.

func EvaluateExpression

func EvaluateExpression(ctx context.Context, expression string) (*ExpressionResult, error)

EvaluateExpression evaluates a string expression of dice, math, or a combination of the two, and returns the resulting ExpressionResult. The evaluation order needs to follow order of operations.

The expression passed must evaluate to a float64 result. A parsable expression could be a simple expression or more complex.

d20
2d20dl1+5
4d6-3d5+30
min(d20,d20)+1
floor(max(d20,2d12k1)/2+3)

EvaluateExpression can likely benefit immensely from optimization and a custom parser implementation along with more fine-grained unit tests/benchmarks.

func (*ExpressionResult) GoString

func (de *ExpressionResult) GoString() string

GoString implements fmt.GoStringer.

func (*ExpressionResult) String

func (de *ExpressionResult) String() string

String implements fmt.Stringer.