checked

Documentation

Overview

Package checked (operator/checked) implements operations bounded by limits that are robust in the event of integer overflow.

Note: Float variants are not fully tested yet.

Index

• Variables
• func Abs[N Number](min N, max N, i N) (N, bool)
• func Add[N Number](min N, max N, a N, b N) (N, bool)
• func Inv[N Number](min N, max N, i N) (N, bool)
• func Mul[N Number](min N, max N, a N, b N) (N, bool)
• func Sub[N Number](min N, max N, a N, b N) (N, bool)
• type Limits
  • func GetLimits[N Number]() Limits[N]
  • func (l Limits[I]) Abs(i I) (I, bool)
  • func (l Limits[I]) Add(a I, b I) (I, bool)
  • func (l Limits[I]) Inv(i I) (I, bool)
  • func (l Limits[I]) Mul(a I, b I) (I, bool)
  • func (l Limits[I]) Sub(a I, b I) (I, bool)
• type Number

Examples

• Limits

Variables

var (
	Int   = Limits[int]{math.MinInt, math.MaxInt}
	Int8  = Limits[int8]{math.MinInt8, math.MaxInt8}
	Int16 = Limits[int16]{math.MinInt16, math.MaxInt16}
	Int32 = Limits[int32]{math.MinInt32, math.MaxInt32}
	Int64 = Limits[int64]{math.MinInt64, math.MaxInt64}

	Uint   = Limits[uint]{0, math.MaxUint}
	Uint8  = Limits[uint8]{0, math.MaxUint8}
	Uint16 = Limits[uint16]{0, math.MaxUint16}
	Uint32 = Limits[uint32]{0, math.MaxUint32}
	Uint64 = Limits[uint64]{0, math.MaxUint64}

	Float32 = Limits[float32]{-math.MaxFloat32, math.MaxFloat32}
	Float64 = Limits[float64]{-math.MaxFloat64, math.MaxFloat64}
)

Filled-in Limits about different types with minimum and maximum set to the largest range supported by the limit.

For signed integers, these are the appropriately sized math.MinInt and math.MaxInt constants. For unsigned integers, these are zero and the appropriately sized math.MaxUint constants. For floats, these are the appropriately sized negative and positive math.MaxFloat constants.

Functions

func Abs

func Abs[N Number](min N, max N, i N) (N, bool)

Abs returns (positive i, true) iff both i and the result lie between min and max inclusive. Otherwise, returns (0, false).

func Add

func Add[N Number](min N, max N, a N, b N) (N, bool)

Add returns (a + b, true) iff a, b, and the result all lie between min and max inclusive, otherwise returns (0, false). This calculation is robust in the event of integer overflow.

func Inv

func Inv[N Number](min N, max N, i N) (N, bool)

Inv returns (-i, true) iff both i and the result lie between min and max inclusive. Otherwise, returns (0, false).

func Mul

func Mul[N Number](min N, max N, a N, b N) (N, bool)

Mul returns (a * b, true) iff a, b, and the result all lie between min and max inclusive, otherwise returns (0, false). This calculation is robust in the event of integer overflow.

func Sub

func Sub[N Number](min N, max N, a N, b N) (N, bool)

Sub returns (a - b, true) iff a, b, and the result all lie between min and max inclusive, otherwise returns (0, false). This calculation is robust in the event of integer overflow.

Types

type Limits

type Limits[N Number] struct {
	Min N
	Max N
}

Limits are a pair of values defining a range between an (inclusive) minimum value and an (inclusive) maximum value.

Example

ExampleLimits demonstrates checked subtraction against custom limits.

package main

import (
	"fmt"

	"github.com/tawesoft/golib/v2/operator/checked"
)

func main() {
	// Call checked.Sub directly with min and max...
	{
		const min = 0
		const max = 99
		result, ok := checked.Sub(min, max, 10, 9)
		fmt.Printf("checked.Sub(min, max, 10, 9): %d, ok?=%t\n", result, ok)
	}

	// Or define a custom limit and call the Sub() method...
	{
		limit := checked.Limits[int]{Min: 0, Max: 99}
		result, ok := limit.Sub(10, 25)
		fmt.Printf("limit.Sub(10, 25): %d, ok?=%t\n", result, ok)
	}

}

Output:

checked.Sub(min, max, 10, 9): 1, ok?=true
limit.Sub(10, 25): 0, ok?=false

func GetLimits

func GetLimits[N Number]() Limits[N]

GetLimits returns a filled-in [Limit] representing the widest possible minimum and maximum values for a generic type.

func (Limits[I]) Abs

func (l Limits[I]) Abs(i I) (I, bool)

Abs returns (positive i, true) iff both i and the result lie between the Limit min and max inclusive. Otherwise, returns (0, false).

func (Limits[I]) Add

func (l Limits[I]) Add(a I, b I) (I, bool)

Add returns (a + b, true) iff a, b, and the result all lie between the Limit min and max inclusive, otherwise returns (0, false). This calculation is robust in the event of integer overflow.

func (Limits[I]) Inv

func (l Limits[I]) Inv(i I) (I, bool)

Inv returns (-i, true) iff both i and the result lie between the Limit min and max inclusive. Otherwise, returns (0, false).

func (Limits[I]) Mul

func (l Limits[I]) Mul(a I, b I) (I, bool)

Mul returns (a * b, true) iff a, b, and the result all lie between the Limit min and max inclusive, otherwise returns (0, false). This calculation is robust in the event of integer overflow.

func (Limits[I]) Sub

func (l Limits[I]) Sub(a I, b I) (I, bool)

Sub returns (a - b, true) iff a, b, and the result all lie between the Limit min and max inclusive, otherwise returns (0, false). This calculation is robust in the event of integer overflow.

type Number

type Number interface {
	constraints.Integer | constraints.Float
}

Number represents any number type that you can support arithmetic using standard Go operators (like a + b, or a ^ b) - i.e. integers & floats.