bigz

bigz/uint128 provides a high-performance Uint128 type that supports standard arithmetic operations. Unlike math/big, operations on Uint128 always produce new values instead of modifying a pointer receiver. A Uint128 value is therefore immutable, just like uint64 and friends.

bigz/uint256 provides similar Uint256 type.

Released under the MIT License.

Installation

go get github.com/Pilatuz/bigz

The name uint128.Uint128 and uint256.Uint256 stutter, so it is recommended either using a "facade" package:

import (
    "github.com/Pilatuz/bigz"
)

// then use bigz.Uint128 type
// then use bigz.Uint256 type

or type aliasing to give it a project-specific name:

import (
    "github.com/Pilatuz/bigz/uint128"
    "github.com/Pilatuz/bigz/uint256"
)

type U128 = uint128.Uint128
type U256 = uint256.Uint256

What's new

The key differences from original package:

• No panics! All methods have wrap-around semantic!
• Zero and Max are functions to prevent modification of global variables.
• New was removed to encourage explicit Uint128{Lo: ..., Hi: ...} initialization. Just not to confuse what is going first, i.e. New(lo, hi) or New(hi, lo).
• Trivial (via big.Int) implementation of fmt.Formatter interface to support for example hex output as fmt.Sprintf("%X", u).
• Trivial (via big.Int) implementation of TextMarshaller and TextUnmarshaler interfaces to support JSON encoding.
• Store/Load methods support little-endian and big-endian byte order.
• New Not and AndNot methods.
• New uint256.Uint256 type.

Quick Start

The 128-bit or 256-bit integer can be initialized in the following ways:

uint128 128-bit package	uint256 256-bit package	Description
u := Uint128{Lo: lo64, Hi: hi64}	u := Uint256{Lo: lo128, Hi: hi128}	Set both lower half and upper half.
u := From64(lo64)	u := From128(lo128)	Set only lower half.
	u := From64(lo64)	Set only lower 64-bit.
u := Zero()	u := Zero()	The same as From64(0).
u := One()	u := One()	The same as From64(1).
u := Max()	u := Max()	The largest possible value.
u := FromBig(big)	u := FromBig(big)	Convert from *big.Int with saturation.
u := FromBigEx(big)	u := FromBigEx(big)	The same as FromBig but provides ok flag.
u, err := FromString("1")	u, err := FromString("1")	Converts from string and provides error.

The following arithmetic operations are supported:

bigz.Uint128	bigz.Uint256	Standard *big.Int equivalent
u.Add, u.Add64	u.Add, u.Add128	big.Int.Add
u.Sub, u.Sub64	u.Sub, u.Sub128	big.Int.Sub
u.Mul, u.Mul64	u.Mul, u.Mul128	big.Int.Mul
u.Div, u.Div64	u.Div, u.Div128	big.Int.Div
u.Mod, u.Mod64	u.Mod, u.Mod128	big.Int.Mod
u.QuoRem, u.QuoRem64	u.QuoRem, u.QuoRem128	big.Int.QuoRem

The following logical and comparison operations are supported:

bigz.Uint128	bigz.Uint256	Standard *big.Int equivalent
u.Equals, u.Equals64	u.Equals, u.Equals128	big.Int.Cmp == 0
u.Cmp, u.Cmp64	u.Cmp u.Cmp64	big.Int.Cmp
u.Not	u.Not	big.Int.Not
u.AndNot, u.AndNot64	u.AndNot, u.AndNot128	big.Int.AndNot
u.And, u.And64	u.And, u.And128	big.Int.And
u.Or, u.Or64	u.Or, u.Or128	big.Int.Or
u.Xor, u.Xor64	u.Xor, u.Xor128	big.Int.Xor
u.Lsh	u.Lsh	big.Int.Lsh
u.Rsh	u.Rsh	big.Int.Rsh

The following bit operations are supported:

bigz.Uint128	bigz.Uint256	Standard 64-bit equivalent
u.RotateLeft	u.RotateLeft	bits.RotateLeft64
u.RotateRight	u.RotateRight	bits.RotateRight64
u.BitLen	u.BitLen	bits.Len64 or big.Int.BitLen
u.LeadingZeros	u.LeadingZeros	bits.LeadingZeros64
u.TrailingZeros	u.TrailingZeros	bits.TrailingZeros64
u.OnesCount	u.OnesCount	bits.OnesCount64
u.Reverse	u.Reverse	bits.Reverse64
u.ReverseBytes	u.ReverseBytes	bits.ReverseBytes64

The following miscellaneous operations are supported:

bigz.Uint128	bigz.Uint256	Standard equivalent
u.String	u.String	big.Int.String
u.Format	u.Format	big.Int.Format
u.Scan	u.Scan	big.Int.Scan
u.MarshalText	u.MarshalText	big.Int.MarshalText
u.UnmarshalText	u.UnmarshalText	big.Int.UnmarshalText
StoreLittleEndian	StoreLittleEndian	binary.LittleEndian.PutUint64
LoadLittleEndian	LoadLittleEndian	binary.LittleEndian.Uint64
StoreBigEndian	StoreBigEndian	binary.BigEndian.PutUint64
LoadBigEndian	LoadBigEndian	binary.BigEndian.Uint64

See the documentation for a complete API specification.