safe

package module
v0.16.0 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2024 License: MIT Imports: 7 Imported by: 10

README

Safe

Go Reference Go Report Card Coverage Status

Purpose

Library that allows you to detect and avoid overflows in operations with integer numbers

Usage

Example:

package main

import (
    "fmt"

    "github.com/akramarenkov/safe"
)

func main() {
    sum, err := safe.Add[int8](124, 3)
    fmt.Println(err)
    fmt.Println(sum)

    sum, err = safe.Add[int8](125, 3)
    fmt.Println(err)
    fmt.Println(sum)
    // Output:
    // <nil>
    // 127
    // integer overflow
    // 0
}

Documentation

Overview

Library that allows you to detect and avoid overflows in operations with integer numbers.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrDivisionByZero   = errors.New("division by zero")
	ErrMissingArguments = errors.New("missing arguments")
	ErrNaN              = errors.New("number is NaN")
	ErrNegativeShift    = errors.New("shift count is negative")
	ErrOverflow         = errors.New("integer overflow")
	ErrPrecisionLoss    = errors.New("loss of precision")
	ErrStepNegative     = errors.New("iterator step is negative")
	ErrStepZero         = errors.New("iterator step is zero")
)

Functions

func Add added in v0.3.0 

func Add[Type constraints.Integer](first, second Type) (Type, error)

Adds two integers and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

Example 
package main

import (
	"fmt"

	"github.com/akramarenkov/safe"
)

func main() {
	sum, err := safe.Add[int8](124, 3)
	fmt.Println(err)
	fmt.Println(sum)

	sum, err = safe.Add[int8](125, 3)
	fmt.Println(err)
	fmt.Println(sum)
}

Output:

<nil>
127
integer overflow
0

func Add3 added in v0.3.0 

func Add3[Type constraints.Integer](first, second, third Type) (Type, error)

Adds three integers and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

func Add3U added in v0.4.0 

func Add3U[Type constraints.Unsigned](first, second, third Type) (Type, error)

Adds three unsigned integers and determines whether an overflow has occurred or not.

Faster than the Add3 function about 70%.

In case of overflow, an error is returned.

func AddDiv added in v0.4.0 

func AddDiv[Type constraints.Integer](first, second, divisor Type) (Type, error)

Calculates the quotient of dividing the sum of two integers by divisor and determines whether an overflow has occurred or not.

In case of overflow or divisor equal to zero, an error is returned.

func AddDivRem added in v0.5.0 

func AddDivRem[Type constraints.Integer](first, second, divisor Type) (Type, error)

Calculates the remainder of dividing the sum of two integers by divisor.

In case of divisor equal to zero, an error is returned.

func AddDivU added in v0.4.0 

func AddDivU[Type constraints.Unsigned](first, second, divisor Type) (Type, error)

Calculates the quotient of dividing the sum of two unsigned integers by divisor and determines whether an overflow has occurred or not.

Not faster than the AddDiv function.

In case of overflow or divisor equal to zero, an error is returned.

func AddM added in v0.3.0 

func AddM[Type constraints.Integer](unmodify bool, addends ...Type) (Type, error)

Adds up several integers and determines whether an overflow has occurred or not.

The function modifies the variadic input arguments. By default, a copy of the variadic input arguments is not created and, if a slice is passed, it will be modified. If a slice is passed as an input argument and it should not be modified, then the unmodify argument must be set to true. In other cases, unmodify can be left as false.

Slower than the Add function about 220%, than the Add3 function about 65%. And overall very slow, be careful.

In case of overflow or missing arguments, an error is returned.

func AddMU added in v0.4.0 

func AddMU[Type constraints.Unsigned](addends ...Type) (Type, error)

Adds up several unsigned integers and determines whether an overflow has occurred or not.

Slower than the AddU function about 170%, than the Add3U function about 80%, faster than the AddM function about 85%.

In case of overflow or missing arguments, an error is returned.

func AddSub added in v0.7.0 

func AddSub[Type constraints.Integer](first, second, subtrahend Type) (Type, error)

Calculates the value of the expression first + second - subtrahend and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

func AddU added in v0.3.0 

func AddU[Type constraints.Unsigned](first, second Type) (Type, error)

Adds two unsigned integers and determines whether an overflow has occurred or not.

Faster than the Add function about 30%.

In case of overflow, an error is returned.

func Dec added in v0.12.0 

func Dec[Type constraints.Integer](begin, end Type) iter.Seq[Type]

A range iterator for safely (without infinite loops due to counter overflow) iterating over integer values from begin to end inclusive towards decrease with a step one.

If begin is lesser than end, then no one iteration of the loop will occur.

func DecSize added in v0.12.0 

func DecSize[Type constraints.Integer](begin, end Type) uint64

Calculates the number of iterations when using Dec. The return value is intended to be used as the size parameter in the make call, so, and because the maximum possible number of iterations is one more than the maximum value for uint64, the return value is truncated to the maximum value for uint64 if the calculated value exceeds it.

func DecStep added in v0.13.0 

func DecStep[Type constraints.Integer](begin, end, step Type) iter.Seq2[uint64, Type]

A range iterator for safely (without infinite loops due to counter overflow) iterating over integer values from begin to end inclusive (if the begin-end range is a multiple of the step) towards decrease with the ability to specify the iteration step.

If begin is lesser than end, then no one iteration of the loop will occur.

As in a regular loop, if the begin-end range is not a multiple of the step, the end value will not be returned.

If a zero or negative step is specified, the iterator will panic.

In addition to the main integer, its index in the begin-end sequence is returned.

func DecStepSize added in v0.13.0 

func DecStepSize[Type constraints.Integer](begin, end, step Type) uint64

Calculates the number of iterations when using DecStep. The return value is intended to be used as the size parameter in the make call, so, and because the maximum possible number of iterations is one more than the maximum value for uint64, the return value is truncated to the maximum value for uint64 if the calculated value exceeds it.

Like DecStep this function panics if a zero or negative step is specified.

func Dist added in v0.14.0 

func Dist[Type constraints.Integer](first, second Type) uint64

Used to safely (using a method that avoids integer overflow) calculate the distance (difference in absolute value) between two numbers.

func Div added in v0.3.0 

func Div[Type constraints.Integer](dividend, divisor Type) (Type, error)

Divides two integers (dividend to divisor) and determines whether an overflow has occurred or not.

The divisor is also checked for equality to zero.

In case of overflow or divisor equal to zero, an error is returned.

func DivM added in v0.3.0 

func DivM[Type constraints.Integer](dividend Type, divisors ...Type) (Type, error)

Divides several integers (dividend to divisors) and determines whether an overflow has occurred or not.

The divisors is also checked for equality to zero.

Slower than the Div function about 15%.

In case of overflow or divisors equal to zero, an error is returned.

func FToI added in v0.3.0 

func FToI[Int constraints.Integer, Flt constraints.Float](number Flt) (Int, error)

Converts a floating point number to an integer and determines whether an overflow has occurred or not.

Number is also checked for equality to NaN.

In case of overflow or number is equality to NaN, an error is returned.

func IToF added in v0.3.0 

func IToF[Flt constraints.Float, Int constraints.Integer](number Int) (Flt, error)

Converts an integer to a floating point number and determines whether loss of precision has occurred or not.

Loss of precision can lead to overflow when converting back to an integer number.

In case of precision is lost, an error is returned.

func IToI added in v0.3.0 

func IToI[TypeTo, TypeFrom constraints.Integer](number TypeFrom) (TypeTo, error)

Converts an integer of one type to an integer of another type and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

func Inc added in v0.12.0 

func Inc[Type constraints.Integer](begin, end Type) iter.Seq[Type]

A range iterator for safely (without infinite loops due to counter overflow) iterating over integer values from begin to end inclusive towards increase with a step one.

If begin is greater than end, then no one iteration of the loop will occur.

func IncSize added in v0.12.0 

func IncSize[Type constraints.Integer](begin, end Type) uint64

Calculates the number of iterations when using Inc. The return value is intended to be used as the size parameter in the make call, so, and because the maximum possible number of iterations is one more than the maximum value for uint64, the return value is truncated to the maximum value for uint64 if the calculated value exceeds it.

func IncStep added in v0.13.0 

func IncStep[Type constraints.Integer](begin, end, step Type) iter.Seq2[uint64, Type]

A range iterator for safely (without infinite loops due to counter overflow) iterating over integer values from begin to end inclusive (if the begin-end range is a multiple of the step) towards increase with the ability to specify the iteration step.

If begin is greater than end, then no one iteration of the loop will occur.

As in a regular loop, if the begin-end range is not a multiple of the step, the end value will not be returned.

If a zero or negative step is specified, the iterator will panic.

In addition to the main integer, its index in the begin-end sequence is returned.

func IncStepSize added in v0.13.0 

func IncStepSize[Type constraints.Integer](begin, end, step Type) uint64

Calculates the number of iterations when using IncStep. The return value is intended to be used as the size parameter in the make call, so, and because the maximum possible number of iterations is one more than the maximum value for uint64, the return value is truncated to the maximum value for uint64 if the calculated value exceeds it.

Like IncStep this function panics if a zero or negative step is specified.

func Iter added in v0.6.0 

func Iter[Type constraints.Integer](begin, end Type) iter.Seq[Type]

A range iterator for safely (without infinite loops due to counter overflow) iterating over integer values from begin to end inclusive with a step one.

If begin is greater than end, the return value will be decremented, otherwise it will be incremented.

Example 
package main

import (
	"fmt"

	"github.com/akramarenkov/safe"
)

func main() {
	for number := range safe.Iter[int8](126, 127) {
		fmt.Println(number)
	}
}

Output:

126
127

func IterSize added in v0.7.0 

func IterSize[Type constraints.Integer](begin, end Type) uint64

Calculates the number of iterations when using Iter. The return value is intended to be used as the size parameter in the make call, so, and because the maximum possible number of iterations is one more than the maximum value for uint64, the return value is truncated to the maximum value for uint64 if the calculated value exceeds it.

func Mul added in v0.3.0 

func Mul[Type constraints.Integer](first, second Type) (Type, error)

Multiplies two integers and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

func Mul3 added in v0.3.0 

func Mul3[Type constraints.Integer](first, second, third Type) (Type, error)

Multiplies three integers and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

func Mul3U added in v0.4.0 

func Mul3U[Type constraints.Unsigned](first, second, third Type) (Type, error)

Multiplies three unsigned integers and determines whether an overflow has occurred or not.

Faster than the Mul3 function about 65%.

In case of overflow, an error is returned.

func MulM added in v0.3.0 

func MulM[Type constraints.Integer](unmodify bool, factors ...Type) (Type, error)

Multiplies several integers and determines whether an overflow has occurred or not.

The function modifies the variadic input arguments. By default, a copy of the variadic input arguments is not created and, if a slice is passed, it will be modified. If a slice is passed as an input argument and it should not be modified, then the unmodify argument must be set to true. In other cases, unmodify can be left as false.

Slower than the Mul function about 10%. And overall very slow, be careful.

In case of overflow or missing arguments, an error is returned.

func MulMU added in v0.4.0 

func MulMU[Type constraints.Unsigned](factors ...Type) (Type, error)

Multiplies several unsigned integers and determines whether an overflow has occurred or not.

Slower than the Mul3U function about 40%, faster than the MulM function about 70%.

In case of overflow or missing arguments, an error is returned.

func Negate added in v0.3.0 

func Negate[Type constraints.Integer](number Type) (Type, error)

Changes the sign of a integer and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

func Pow added in v0.3.0 

func Pow[Type, TypePower constraints.Integer](base Type, power TypePower) (Type, error)

Raises base to a power and determines whether an overflow has occurred or not.

Straightforward and slow implementation. Be careful.

In case of overflow, an error is returned.

func Pow10 added in v0.3.0 

func Pow10[Type, TypePower constraints.Integer](power TypePower) (Type, error)

Raises 10 to a power and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

func Shift added in v0.8.0 

func Shift[Type, CountType constraints.Integer](number Type, count CountType) (Type, error)

Shifts an integer left to specified shift count and determines whether an overflow has occurred or not.

Shift count is also checked for negativity.

In case of overflow or shift count is negative, an error is returned.

func Step added in v0.12.0 

func Step[Type constraints.Integer](begin, end, step Type) iter.Seq2[uint64, Type]

A range iterator for safely (without infinite loops due to counter overflow) iterating over integer values from begin to end inclusive (if the begin-end range is a multiple of the step) with the ability to specify the iteration step.

If begin is greater than end, the return value will be decremented, otherwise it will be incremented.

As in a regular loop, if the begin-end range is not a multiple of the step, the end value will not be returned.

If a zero or negative step is specified, the iterator will panic.

In addition to the main integer, its index in the begin-end sequence is returned.

Example 
package main

import (
	"fmt"

	"github.com/akramarenkov/safe"
)

func main() {
	for _, number := range safe.Step[int8](126, 127, 2) {
		fmt.Println(number)
	}
}

Output:

126

func StepSize added in v0.12.0 

func StepSize[Type constraints.Integer](begin, end, step Type) uint64

Calculates the number of iterations when using Step. The return value is intended to be used as the size parameter in the make call, so, and because the maximum possible number of iterations is one more than the maximum value for uint64, the return value is truncated to the maximum value for uint64 if the calculated value exceeds it.

Like Step this function panics if a zero or negative step is specified.

func Sub added in v0.3.0 

func Sub[Type constraints.Integer](minuend, subtrahend Type) (Type, error)

Subtracts two integers (subtrahend from minuend) and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

func Sub3 added in v0.3.0 

func Sub3[Type constraints.Integer](minuend, subtrahend, deductible Type) (Type, error)

Subtracts three integers (subtrahend, deductible from minuend) and determines whether an overflow has occurred or not.

In case of overflow, an error is returned.

func Sub3U added in v0.4.0 

func Sub3U[Type constraints.Unsigned](minuend, subtrahend, deductible Type) (Type, error)

Subtracts three unsigned integers (subtrahend, deductible from minuend) and determines whether an overflow has occurred or not.

Faster than the Sub3 function about 75%.

In case of overflow, an error is returned.

func SubDiv added in v0.4.0 

func SubDiv[Type constraints.Integer](minuend, subtrahend, divisor Type) (Type, error)

Calculates the quotient of dividing the difference of two integers by divisor and determines whether an overflow has occurred or not.

In case of overflow or divisor equal to zero, an error is returned.

func SubDivRem added in v0.5.0 

func SubDivRem[Type constraints.Integer](minuend, subtrahend, divisor Type) (Type, error)

Calculates the remainder of dividing the difference of two integers by divisor and determines whether an overflow has occurred or not.

In case of overflow or divisor equal to zero, an error is returned.

func SubDivU added in v0.4.0 

func SubDivU[Type constraints.Unsigned](minuend, subtrahend, divisor Type) (Type, error)

Calculates the quotient of dividing the difference of two unsigned integers by divisor and determines whether an overflow has occurred or not.

Faster than the SubDiv function about 30%.

In case of overflow or divisor equal to zero, an error is returned.

func SubM added in v0.3.0 

func SubM[Type constraints.Integer](unmodify bool, minuend Type, subtrahends ...Type) (Type, error)

Subtracts several integers (subtrahends from minuend) and determines whether an overflow has occurred or not.

The function modifies the variadic input arguments. By default, a copy of the variadic input arguments is not created and, if a slice is passed, it will be modified. If a slice is passed as an input argument and it should not be modified, then the unmodify argument must be set to true. In other cases, unmodify can be left as false.

Slower than the Sub function about 160%, than the Sub3 function about 40%. And overall very slow, be careful.

In case of overflow, an error is returned.

func SubMU added in v0.4.0 

func SubMU[Type constraints.Unsigned](minuend Type, subtrahends ...Type) (Type, error)

Subtracts several unsigned integers (subtrahends from minuend) and determines whether an overflow has occurred or not.

Slower than the SubU function about 90%, than the Sub3U function about 100%, faster than the SubM function about 85%.

In case of overflow, an error is returned.

func SubU added in v0.3.0 

func SubU[Type constraints.Unsigned](minuend, subtrahend Type) (Type, error)

Subtracts two unsigned integers (subtrahend from minuend) and determines whether an overflow has occurred or not.

Faster than the Sub function about 10%.

In case of overflow, an error is returned.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
internal
clone
Internal package with slightly faster, for this module, cloning function.
 Internal package with slightly faster, for this module, cloning function.
consts
Internal package with constants common to this module.
 Internal package with constants common to this module.
env
Internal package with environment constants common to this module.
 Internal package with environment constants common to this module.
inspect
Internal package used to check if functions work correctly.
 Internal package used to check if functions work correctly.
inspect/dataset
Internal package used to check if functions work correctly by dataset.
 Internal package used to check if functions work correctly by dataset.
inspect/dataset/filler
Internal package with various fillers that fill arguments of dataset item by values.
 Internal package with various fillers that fill arguments of dataset item by values.
inspect/incrementor
Internal package with Incrementor which checks that the arguments change as if they were incremented by nested loops.
 Internal package with Incrementor which checks that the arguments change as if they were incremented by nested loops.
inspect/types
Internal package with types used when inspecting.
 Internal package with types used when inspecting.
iterator
Internal package with a copy of the iterator from the main code used in internal packages and tests.
 Internal package with a copy of the iterator from the main code used in internal packages and tests.
research/add
Internal package that research overflow when adding integers.
 Internal package that research overflow when adding integers.
research/itof
Internal package that research problems of converting integer values to floating point values.
 Internal package that research problems of converting integer values to floating point values.
Used to determine the parameters of integer types (minimum, maximum values ​​and bit size).
 Used to determine the parameters of integer types (minimum, maximum values ​​and bit size).
Package with assist functions that verify variables to corresponds some conditions.
 Package with assist functions that verify variables to corresponds some conditions.

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.