go-imath

Package containing some integral constants and elementary functions for integral arguments.

Summary

Go standard math package lacks some frequently used integral functions. This package tries to fill the gap, providing their effective and convenient implementations.

Functions have the same or similar names as their float64 equivalents from math package (if there are any). Since Go does not allow overloading, constants and functions related to each of builtin integral types (except uintptr and type aliases like byte or rune, which are not covered by this package) are grouped within subpackage with a corresponding name (ix for int, i8 for int8, ...; ux for uint, u8 for uint8, ...). Functions defined only for few of the types (like Power functions) are kept in the root imath package.

Import

import (
	"github.com/adam-lavrik/go-imath/ix" // int-related functions
	"github.com/adam-lavrik/go-imath/u32" // uint32-related function
	...
)

Types

• T - integer type, package is centered on (uint8 for u8, int for ix, ...)
• UT - unsigned type, complementary to signed T (uint8 for int8, uint for int, ...)
• ST - signed type, complementary to unsigned T (int8 for uint8, int for uint, ...)

Constants

• Size - size of type value in bytes
• BitSize - same in bits
• Minimal - minimal possible value of type
• Maximal - maximal possible value of type

Platform dependent

Name	Type	Value (32-bit)	Value (64-bit)
ix.Size	uintptr	4	8
ix.BitSize	uintptr	32	64
ix.Minimal	int	-2147483648	-9223372036854775808
ix.Maximal	int	2147483647	9223372036854775807
ux.Size	uintptr	4	8
ux.BitSize	uintptr	32	64
ux.Minimal	uint	0	0
ux.Maximal	uint	4294967295	18446744073709551615

Platform independent

Name	Type	Value
i8.Size	uintptr	1
i8.BitSize	uintptr	8
i8.Minimal	int8	-128
i8.Maximal	int8	127
u8.Size	uintptr	1
u8.BitSize	uintptr	8
u8.Minimal	uint8	0
u8.Maxnimal	uint8	255
i16.Size	uintptr	2
i16.BitSize	uintptr	16
i16.Minimal	int16	-32768
i16.Maximal	int16	32767
u16.Size	uintptr	2
u16.BitSize	uintptr	16
u16.Minimal	uint16	0
u16.Maximal	uint16	65535
i32.Size	uintptr	4
i32.BitSize	uintptr	32
i32.Minimal	int32	-2147483648
i32.Maximal	int32	2147483647
u32.Size	uintptr	4
u32.BitSize	uintptr	32
u32.Minimal	uint32	0
u32.Maximal	uint32	4294967295
i64.Size	uintptr	8
i64.BitSize	uintptr	64
i64.Minimal	int64	-9223372036854775808
i64.Maximal	int64	9223372036854775807
u64.Size	uintptr	8
u64.BitSize	uintptr	64
u64.Minimal	uint64	0
u64.Maximal	uint64	18446744073709551615

Functions

i#.Abs(value int#) int#

Absolute value of signed integer. Argument and result have the same type.

Examples:

a0 := ix.Abs(-16) // a0 == int(16)
a1 := i8.Abs(42) // a1 == int8(42)

Important: since the lowest negative values of integral signed types have no corresponding positive values, result of Abs(i#.Minimal) is falsely equal to the argument:

a2 := i16.Abs(-32768) // a2 == int16(-32768)

i#.Absu(value int#) uint#

Absolute value of signed integer. Argument is of signed integer type, and result is of the complementary unsigned integer type thus can hold all positive values corresponding to all possible negative values of argument type.

Examples:

a0 := ix.Absu(-16) // a0 == uint(16)
a1 := i8.Absu(42) // a1 == uint8(42)
a2 := i16.Absu(-32768) // a2 == uint16(32768)

i#.Copysign(target, source int#) int#

Value with magnitude of target and sign of source. Zero target always produces zero result. Non-zero target and zero source produce positive result.

For an obvious reason these functions take only signed arguments.

Examples:

c0 := ix.Copysign(16, 0) // c0 == int(16)
c1 := i8.Copysign(-38, 1) // c1 == int8(38)
c2 := i64.Copysing(42, -1) // c2 == int64(-42)

Important: since the lowest negative values of integral signed types have no corresponding positive values, their sign cannot be set to positive. This limitation cannot be avoided.

#.DivMod(dividend, divisor #) (#, #)

Quotient and remainder of dividend and divisor. Zero divisor causes division by zero error.

Examples:

q0, d0 := ux.DivMod(15, 8) // q0 == uint(1), d0 == uint(7)
q1, d1 := i16.DivMod(320, 64) // q1 == int16(5), d1 == int16(0)
q2, d2 := i64.DivMod(79, 0) // Error

#.GCD(value_0, value_1 #) uint#

Greatest common divisor of two integers. Arguments can be of signed or unsigned integer type, while result is always unsigned (same type for unsigned arguments or complementary unsigned for signed ones).

Examples:

g0 = ix.GCD(48, 32) // g0 == uint(16)
g1 = u16.GCD(45, 0) // g1 == uint16(45)
g2 = i8.GCD(-42, -8) // g2 == uint8(2)
g3 = i32.GCD(-28, 21) // g3 == uint32(7)

#.Is2Power(value #) bool

Check whether the value is an integer power of 2 (true) or not (false). Zero and negative values always produce false.

Examples:

i2p0 := ix.Is2Power(14) // i2p0 == false
i2p1 := u8.Is2Power(128) // i2p1 == true
i2p2 := i16.Is2Power(-7) // i2p2 == false

#.IsOdd(value #) bool

Check whether the value is odd (true) or not (false).

io0 := ux.IsOdd(742) // io0 == false
io1 := u8.IsOdd(0) // io1 == true
io2 := i32.IsOdd(-11345) // io2 == true

#.LCM(value_0, value_1 #) uint#

Least common multiply of two integers. Arguments can be of signed or unsigned integer type, while result is always unsigned (same type for unsigned arguments or complementary unsigned for signed ones).

Examples:

l0 = ix.LCM(48, 32) // l0 == uint(96)
l1 = u16.LCM(45, 0) // l1 == uint16(0)
l2 = i8.LCM(-42, -8) // l2 == uint8(168)
l3 = i32.LCM(-28, 21) // l3 == uint32(84)

#.Min(value_0, value_1 #)

Minimal of two integers.

Examples:

mi0 := ix.Min(13, -42) // mi0 == int(-42)
mi1 := u8.Min(255, 255) // mi1 == uint8(255)

#.Mins(value #, values ...#)

Minimal of one or more integers.

Examples:

mis0 := ix.Mins(-42) // mis0 == int(-42)
mis1 := u8.Mins(255, 255, 14) // mis1 == uint8(14)

#.MinSlice(values []#)

Minimal of slice items. Empty slice causes error.

Examples:

mis := ix.MinSlice([]int{1, - 3, -42}) // mis == int(-42)

#.MinSliceChecked(values []#) (#, bool)

Minimal of slice items. For an empty slice second result is true. Otherwise it is false, and first result is meaningful.

Examples:

misc, empty := ix.MinSliceChecked([]int{1, - 3, -42}) // misc == int(-42), empty == false

#.Max(value_0, value_1 #)

Maximal of two integers.

Examples:

ma0 := ix.Max(13, -42) // ma0 == int(13)
ma1 := u8.Max(255, 255) // ma1 == uint8(255)

#.Maxs(value #, values ...#)

Maximal of one or more integers.

Examples:

mas0 := ix.Maxs(-42) // mas0 == int(-42)
mas1 := u8.Maxs(255, 255, 14) // mas1 == uint8(255)

#.MaxSlice(values []#)

Maximal of slice items. Empty slice causes error.

Examples:

mas := ix.MaxSlice([]int{1, - 3, -42}) // mas == int(1)

#.MaxSliceChecked(values []#) (#, bool)

Maximal of slice items. For an empty slice second result is true. Otherwise it is false, and first result is meaningful.

Examples:

masc, empty := ix.MaxSliceChecked([]int{1, - 3, -42}) // masc == int(1), empty == false

#.MinMax(value_0, value_1 #) (#, #)

Minimal (first) and maximal (second) of two integers.

Examples:

min0, max0 := ix.MinMax(13, -42) // min0 == int(-42), max0 == int(13)
min1, max1 := u8.MinMax(255, 255) // min1 == uint8(255), max1 == uint8(255)

#.MinMaxs(value #, values ...#) (#, #)

Minimal (first) and maximal (second) of one or more integers.

Examples:

mins1, maxs1 := u8.MinMaxs(255, 255, 14) // mins1 == uint8(14), maxs1 == uint8(255)

#.MinMaxSlice(values []#) (#, #)

Minimal (first) and maximal (second) of slice items. Empty slice causes error.

Examples:

mins, maxs := ix.MinMaxSlice([]int{1, - 3, -42}) // mins == int(-42), maxs == int(1)

#.MinMaxSliceChecked(values []#) (#, #, bool)

Minimal (first) and maximal (second) of slice items. For an empty slice third result is true. Otherwise it is false, and first and second results are meaningful.

Examples:

minsc, maxsc, empty := ix.MaxSliceChecked([]int{1, - 3, -42}) // minsc == int(-42), maxsc == int(1), empty == false

i#.Sign (value int#) int#

Signum of signed integer:

• -1 if value < 0
• 0 if value = 0
• 1 if value > 0

Examples:

s0 := ix.Sign(99) // s0 == int(1)
s1 := i16.Sign(0) // s1 == int16(0)
s2 := i64.Sign(-1234) // s2 == int64(-1)

u#.Sign (value uint#) uint#

Signum of unsigned integer:

• 0 if value = 0
• 1 if value > 0

Examples:

s0 := ux.Sign(99) // s0 == uint(1)
s1 := u16.Sign(0) // s1 == uint16(0)

i#.SignBit (value int#) int#

Result of the same signed type as value with all bits equal to value's highest bit:

• -1 if value < 0
• 0 if value >= 0

Examples:

s0 := ix.SignBit(99) // s0 == int(0)
s1 := i16.SignBit(0) // s1 == int16(0)
s2 := i64.SignBit(-1234) // s2 == int64(-1)

ix.Fibonacci(index int) int

i64.Fibonacci(index int) int64

Fibonacci sequence member with corresponding index. index can be zero or negative.

Examples:

fi0 := ix.Fibonacci(0) // fi0 == int(0)
fi1 := i64.Fibonacci(5) // fi1 == int64(5)
fi2 := ix.Fibonacci(-4) // fi2 == int(-3)
fi3 := i64.Fibonacci(-5) // fi3 == int64(5)

ux.Fibonacci(index uint) uint

u64.Fibonacci(index uint) uint64

Fibonacci sequence member with corresponding index. index can be zero.

Examples:

fu0 := ix.Fibonacci(0) // fu0 == int(0)
fu1 := i64.Fibonacci(6) // fu == int64(8)

ix.Pow(base int, exponent uint) int

i64.Pow(base int64, exponent uint) int64

ux.Pow(base uint, exponent uint) uint

u64.Pow(base uint64, exponent uint) uint64

Exponentiation of integral base and non-negative exponent.

Important:

• if exponent is 0, result is always 1, even if base is 0 too;
• since result values grow rapidly, this function is implemented only for int, uint, int64 and uint64 types.

Examples:

p0 := ux.Pow(17, 2) // p0 == uint(289)
p1 := i64.Pow(-41, 7) // p1 == int64(-194754273881)
p2 := u64.Pow(0, 5) // p2 == uint64(0)
p3 := ix.Pow(-122, 0) // p3 == int(1)

(c) Adam Lavrik [email protected], 2020