checkedmath

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 10, 2026 License: MIT Imports: 3 Imported by: 0

README

checkedmath

Checked integer arithmetic for Go. Prevents overflow, underflow, and division by zero by returning errors instead of wrapping or panicking.

Installation

go get github.com/Gustrb/checkedmath

Requires Go 1.21+ (generics). Dependency: golang.org/x/exp (for constraints.Integer).

Quick start

Use the pre-bound functions for standard types:

package main

import (
	"fmt"
	"github.com/Gustrb/checkedmath"
)

func main() {
	// Addition — returns error on overflow
	sum, err := checkedmath.Add64(100, 200)
	if err != nil {
		fmt.Println("overflow:", err)
		return
	}
	fmt.Println(sum) // 300

	// Division by zero
	_, err = checkedmath.Div64(10, 0)
	if err != nil {
		fmt.Println(err) // division by zero
	}
}

Chain operations with the builder and check once at the end:

	result, err := checkedmath.NewInt64(10).
		Add(20).
		Mul(3).
		Div(2).
		Result()
	if err != nil {
		return err // overflow or division by zero
	}
	// result == 45

Supported types and operations

Type Add Sub Mul Div Builder Constructor
int8 Add8, Sub8, Mul8, Div8 BuilderInt8 NewInt8
int16 Add16, Sub16, Mul16, Div16 BuilderInt16 NewInt16
int32 Add32, Sub32, Mul32, Div32 BuilderInt32 NewInt32
int64 Add64, Sub64, Mul64, Div64 BuilderInt64 NewInt64
uint8 AddU8, SubU8, MulU8, DivU8 BuilderUint8 NewUint8
uint16 AddU16, SubU16, MulU16, DivU16 BuilderUint16 NewUint16
uint32 AddU32, SubU32, MulU32, DivU32 BuilderUint32 NewUint32
uint64 AddU64, SubU64, MulU64, DivU64 BuilderUint64 NewUint64
  • Add / Sub / Mul: return ErrOverflow when the result would exceed the type’s range (or underflow for unsigned Sub).
  • Div: returns ErrDivisionByZero when the divisor is zero.

Errors

  • checkedmath.ErrOverflow — result would overflow (or underflow for unsigned subtraction).
  • checkedmath.ErrDivisionByZero — division by zero.

Builder pattern

Builders let you chain operations and handle a single error at the end. After an error, later steps are no-ops and the same error is returned from Result().

	result, err := checkedmath.NewUint64(100).
		Mul(3).
		Div(2).
		DivRounded(7).
		Result()
  • DivRounded(n) — computes (value + n/2) / n (rounded division). Still returns ErrDivisionByZero if n == 0.

Custom bounds

For custom ranges (e.g. clamped values), use the generic constructors:

  • BoundedAdd[T](upper, lower T) func(a, b T) (T, error)
  • BoundedSub[T](upper, lower T) func(a, b T) (T, error)
  • BoundedMul[T](upper, lower T) func(a, b T) (T, error)
  • BoundedDiv[T](upper, lower T) func(a, b T) (T, error)

T must satisfy constraints.Integer. Example for int64 with standard range:

	add := checkedmath.BoundedAdd[int64](math.MaxInt64, math.MinInt64)
	sum, err := add(a, b)

License

See repository.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Add16 = BoundedAdd[int16](math.MaxInt16, math.MinInt16)
View Source 
var Add32 = BoundedAdd[int32](math.MaxInt32, math.MinInt32)
View Source 
var Add64 = BoundedAdd[int64](math.MaxInt64, math.MinInt64)
View Source 
var Add8 = BoundedAdd[int8](math.MaxInt8, math.MinInt8)
View Source 
var AddU16 = BoundedAdd[uint16](math.MaxUint16, 0)
View Source 
var AddU32 = BoundedAdd[uint32](math.MaxUint32, 0)
View Source 
var AddU64 = BoundedAdd[uint64](math.MaxUint64, 0)
View Source 
var AddU8 = BoundedAdd[uint8](math.MaxUint8, 0)
View Source 
var Div16 = BoundedDiv[int16](math.MaxInt16, math.MinInt16)
View Source 
var Div32 = BoundedDiv[int32](math.MaxInt32, math.MinInt32)
View Source 
var Div64 = BoundedDiv[int64](math.MaxInt64, math.MinInt64)
View Source 
var Div8 = BoundedDiv[int8](math.MaxInt8, math.MinInt8)
View Source 
var DivU16 = BoundedDiv[uint16](math.MaxUint16, 0)
View Source 
var DivU32 = BoundedDiv[uint32](math.MaxUint32, 0)
View Source 
var DivU64 = BoundedDiv[uint64](math.MaxUint64, 0)
View Source 
var DivU8 = BoundedDiv[uint8](math.MaxUint8, 0)
View Source 
var ErrDivisionByZero = errors.New("division by zero")
View Source 
var ErrOverflow = errors.New("integer overflow")
View Source 
var Mul16 = BoundedMul[int16](math.MaxInt16, math.MinInt16)
View Source 
var Mul32 = BoundedMul[int32](math.MaxInt32, math.MinInt32)
View Source 
var Mul64 = BoundedMul[int64](math.MaxInt64, math.MinInt64)
View Source 
var Mul8 = BoundedMul[int8](math.MaxInt8, math.MinInt8)
View Source 
var MulU16 = BoundedMul[uint16](math.MaxUint16, 0)
View Source 
var MulU32 = BoundedMul[uint32](math.MaxUint32, 0)
View Source 
var MulU64 = BoundedMul[uint64](math.MaxUint64, 0)
View Source 
var MulU8 = BoundedMul[uint8](math.MaxUint8, 0)
View Source 
var Sub16 = BoundedSub[int16](math.MaxInt16, math.MinInt16)
View Source 
var Sub32 = BoundedSub[int32](math.MaxInt32, math.MinInt32)
View Source 
var Sub64 = BoundedSub[int64](math.MaxInt64, math.MinInt64)
View Source 
var Sub8 = BoundedSub[int8](math.MaxInt8, math.MinInt8)
View Source 
var SubU16 = BoundedSub[uint16](math.MaxUint16, 0)
View Source 
var SubU32 = BoundedSub[uint32](math.MaxUint32, 0)
View Source 
var SubU64 = BoundedSub[uint64](math.MaxUint64, 0)
View Source 
var SubU8 = BoundedSub[uint8](math.MaxUint8, 0)

Functions

func BoundedAdd 

func BoundedAdd[T constraints.Integer](upper, lower T) func(a, b T) (T, error)

func BoundedDiv 

func BoundedDiv[T constraints.Integer](upper, lower T) func(a, b T) (T, error)

func BoundedMul 

func BoundedMul[T constraints.Integer](upper, lower T) func(a, b T) (T, error)

func BoundedSub 

func BoundedSub[T constraints.Integer](upper, lower T) func(a, b T) (T, error)

Types

type BuilderInt8 

type BuilderInt8 struct {
	// contains filtered or unexported fields
}

Builder provides a monad-like pattern for chaining checked math operations. Operations are only executed if no previous error occurred. This allows cleaner code without repetitive error checking at each step.

func NewInt8 

func NewInt8(value int8) *BuilderInt8

New creates a new Builder with the given initial value.

func (*BuilderInt8) Add 

func (b *BuilderInt8) Add(n int8) *BuilderInt8

Add adds the given value using checked addition. If a previous operation failed, this is a no-op.

func (*BuilderInt8) Div 

func (b *BuilderInt8) Div(n int8) *BuilderInt8

Div performs integer division. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderInt8) DivRounded 

func (b *BuilderInt8) DivRounded(n int8) *BuilderInt8

DivRounded performs integer division with rounding (adds divisor/2 before dividing). This minimizes precision loss for positive values. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderInt8) Mul 

func (b *BuilderInt8) Mul(n int8) *BuilderInt8

Mul multiplies by the given value using checked multiplication. If a previous operation failed, this is a no-op.

func (*BuilderInt8) Result 

func (b *BuilderInt8) Result() (int8, error)

Result returns the final value and any error that occurred.

func (*BuilderInt8) Sub 

func (b *BuilderInt8) Sub(n int8) *BuilderInt8

Sub subtracts the given value using checked subtraction. If a previous operation failed, this is a no-op.

type BuilderInt16 

type BuilderInt16 struct {
	// contains filtered or unexported fields
}

Builder provides a monad-like pattern for chaining checked math operations. Operations are only executed if no previous error occurred. This allows cleaner code without repetitive error checking at each step.

func NewInt16 

func NewInt16(value int16) *BuilderInt16

New creates a new Builder with the given initial value.

func (*BuilderInt16) Add 

func (b *BuilderInt16) Add(n int16) *BuilderInt16

Add adds the given value using checked addition. If a previous operation failed, this is a no-op.

func (*BuilderInt16) Div 

func (b *BuilderInt16) Div(n int16) *BuilderInt16

Div performs integer division. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderInt16) DivRounded 

func (b *BuilderInt16) DivRounded(n int16) *BuilderInt16

DivRounded performs integer division with rounding (adds divisor/2 before dividing). This minimizes precision loss for positive values. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderInt16) Mul 

func (b *BuilderInt16) Mul(n int16) *BuilderInt16

Mul multiplies by the given value using checked multiplication. If a previous operation failed, this is a no-op.

func (*BuilderInt16) Result 

func (b *BuilderInt16) Result() (int16, error)

Result returns the final value and any error that occurred.

func (*BuilderInt16) Sub 

func (b *BuilderInt16) Sub(n int16) *BuilderInt16

Sub subtracts the given value using checked subtraction. If a previous operation failed, this is a no-op.

type BuilderInt32 

type BuilderInt32 struct {
	// contains filtered or unexported fields
}

Builder provides a monad-like pattern for chaining checked math operations. Operations are only executed if no previous error occurred. This allows cleaner code without repetitive error checking at each step.

func NewInt32 

func NewInt32(value int32) *BuilderInt32

New creates a new Builder with the given initial value.

func (*BuilderInt32) Add 

func (b *BuilderInt32) Add(n int32) *BuilderInt32

Add adds the given value using checked addition. If a previous operation failed, this is a no-op.

func (*BuilderInt32) Div 

func (b *BuilderInt32) Div(n int32) *BuilderInt32

Div performs integer division. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderInt32) DivRounded 

func (b *BuilderInt32) DivRounded(n int32) *BuilderInt32

DivRounded performs integer division with rounding (adds divisor/2 before dividing). This minimizes precision loss for positive values. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderInt32) Mul 

func (b *BuilderInt32) Mul(n int32) *BuilderInt32

Mul multiplies by the given value using checked multiplication. If a previous operation failed, this is a no-op.

func (*BuilderInt32) Result 

func (b *BuilderInt32) Result() (int32, error)

Result returns the final value and any error that occurred.

func (*BuilderInt32) Sub 

func (b *BuilderInt32) Sub(n int32) *BuilderInt32

Sub subtracts the given value using checked subtraction. If a previous operation failed, this is a no-op.

type BuilderInt64 

type BuilderInt64 struct {
	// contains filtered or unexported fields
}

Builder provides a monad-like pattern for chaining checked math operations. Operations are only executed if no previous error occurred. This allows cleaner code without repetitive error checking at each step.

func NewInt64 

func NewInt64(value int64) *BuilderInt64

New creates a new Builder with the given initial value.

func (*BuilderInt64) Add 

func (b *BuilderInt64) Add(n int64) *BuilderInt64

Add adds the given value using checked addition. If a previous operation failed, this is a no-op.

func (*BuilderInt64) Div 

func (b *BuilderInt64) Div(n int64) *BuilderInt64

Div performs integer division. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderInt64) DivRounded 

func (b *BuilderInt64) DivRounded(n int64) *BuilderInt64

DivRounded performs integer division with rounding (adds divisor/2 before dividing). This minimizes precision loss for positive values. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderInt64) Mul 

func (b *BuilderInt64) Mul(n int64) *BuilderInt64

Mul multiplies by the given value using checked multiplication. If a previous operation failed, this is a no-op.

func (*BuilderInt64) Result 

func (b *BuilderInt64) Result() (int64, error)

Result returns the final value and any error that occurred.

func (*BuilderInt64) Sub 

func (b *BuilderInt64) Sub(n int64) *BuilderInt64

Sub subtracts the given value using checked subtraction. If a previous operation failed, this is a no-op.

type BuilderUint8 

type BuilderUint8 struct {
	// contains filtered or unexported fields
}

BuilderUint8 provides a monad-like pattern for chaining checked math operations. Operations are only executed if no previous error occurred.

func NewUint8 

func NewUint8(value uint8) *BuilderUint8

NewUint8 creates a new Builder with the given initial value.

func (*BuilderUint8) Add 

func (b *BuilderUint8) Add(n uint8) *BuilderUint8

Add adds the given value using checked addition.

func (*BuilderUint8) Div 

func (b *BuilderUint8) Div(n uint8) *BuilderUint8

Div performs integer division. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderUint8) DivRounded 

func (b *BuilderUint8) DivRounded(n uint8) *BuilderUint8

DivRounded performs integer division with rounding (adds divisor/2 before dividing).

func (*BuilderUint8) Mul 

func (b *BuilderUint8) Mul(n uint8) *BuilderUint8

Mul multiplies by the given value using checked multiplication.

func (*BuilderUint8) Result 

func (b *BuilderUint8) Result() (uint8, error)

Result returns the final value and any error that occurred.

func (*BuilderUint8) Sub 

func (b *BuilderUint8) Sub(n uint8) *BuilderUint8

Sub subtracts the given value using checked subtraction.

type BuilderUint16 

type BuilderUint16 struct {
	// contains filtered or unexported fields
}

BuilderUint16 provides a monad-like pattern for chaining checked math operations. Operations are only executed if no previous error occurred.

func NewUint16 

func NewUint16(value uint16) *BuilderUint16

NewUint16 creates a new Builder with the given initial value.

func (*BuilderUint16) Add 

func (b *BuilderUint16) Add(n uint16) *BuilderUint16

Add adds the given value using checked addition.

func (*BuilderUint16) Div 

func (b *BuilderUint16) Div(n uint16) *BuilderUint16

Div performs integer division. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderUint16) DivRounded 

func (b *BuilderUint16) DivRounded(n uint16) *BuilderUint16

DivRounded performs integer division with rounding (adds divisor/2 before dividing).

func (*BuilderUint16) Mul 

func (b *BuilderUint16) Mul(n uint16) *BuilderUint16

Mul multiplies by the given value using checked multiplication.

func (*BuilderUint16) Result 

func (b *BuilderUint16) Result() (uint16, error)

Result returns the final value and any error that occurred.

func (*BuilderUint16) Sub 

func (b *BuilderUint16) Sub(n uint16) *BuilderUint16

Sub subtracts the given value using checked subtraction.

type BuilderUint32 

type BuilderUint32 struct {
	// contains filtered or unexported fields
}

BuilderUint32 provides a monad-like pattern for chaining checked math operations. Operations are only executed if no previous error occurred.

func NewUint32 

func NewUint32(value uint32) *BuilderUint32

NewUint32 creates a new Builder with the given initial value.

func (*BuilderUint32) Add 

func (b *BuilderUint32) Add(n uint32) *BuilderUint32

Add adds the given value using checked addition.

func (*BuilderUint32) Div 

func (b *BuilderUint32) Div(n uint32) *BuilderUint32

Div performs integer division. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderUint32) DivRounded 

func (b *BuilderUint32) DivRounded(n uint32) *BuilderUint32

DivRounded performs integer division with rounding (adds divisor/2 before dividing).

func (*BuilderUint32) Mul 

func (b *BuilderUint32) Mul(n uint32) *BuilderUint32

Mul multiplies by the given value using checked multiplication.

func (*BuilderUint32) Result 

func (b *BuilderUint32) Result() (uint32, error)

Result returns the final value and any error that occurred.

func (*BuilderUint32) Sub 

func (b *BuilderUint32) Sub(n uint32) *BuilderUint32

Sub subtracts the given value using checked subtraction.

type BuilderUint64 

type BuilderUint64 struct {
	// contains filtered or unexported fields
}

Builder provides a monad-like pattern for chaining checked math operations. Operations are only executed if no previous error occurred. This allows cleaner code without repetitive error checking at each step.

func NewUint64 

func NewUint64(value uint64) *BuilderUint64

New creates a new Builder with the given initial value.

func (*BuilderUint64) Add 

func (b *BuilderUint64) Add(n uint64) *BuilderUint64

Add adds the given value using checked addition. If a previous operation failed, this is a no-op.

func (*BuilderUint64) Div 

func (b *BuilderUint64) Div(n uint64) *BuilderUint64

Div performs integer division. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderUint64) DivRounded 

func (b *BuilderUint64) DivRounded(n uint64) *BuilderUint64

DivRounded performs integer division with rounding (adds divisor/2 before dividing). This minimizes precision loss for positive values. If a previous operation failed, this is a no-op. Returns ErrDivisionByZero if divisor is zero.

func (*BuilderUint64) Mul 

func (b *BuilderUint64) Mul(n uint64) *BuilderUint64

Mul multiplies by the given value using checked multiplication. If a previous operation failed, this is a no-op.

func (*BuilderUint64) Result 

func (b *BuilderUint64) Result() (uint64, error)

Result returns the final value and any error that occurred.

func (*BuilderUint64) Sub 

func (b *BuilderUint64) Sub(n uint64) *BuilderUint64

Sub subtracts the given value using checked subtraction. If a previous operation failed, this is a no-op.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.