bigx

README

bigx

bigx/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.

bigx/uint256 provides similar Uint256 type (note, 256-bit division is still subject for some optimizations).

Released under the MIT License.

Installation

go get github.com/Pilatuz/bigx/v2

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

import (
    "github.com/Pilatuz/bigx/v2"
)

// then use bigx.Uint128 type
// then use bigx.Uint256 type

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

import (
    "github.com/Pilatuz/bigx/v2/uint128"
    "github.com/Pilatuz/bigx/v2/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.
• 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 := FromBigX(big)	u := FromBigX(big)	The same as FromBig but provides ok flag.

The following arithmetic operations are supported:

bigx.Uint128	bigx.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:

bigx.Uint128	bigx.Uint1256	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:

bigx.Uint128	bigx.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:

bigx.Uint128	bigx.Uint256	Standard equivalent
u.String	u.String	big.Int.String
u.Format	u.Format	big.Int.Format
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.

Documentation

Overview

Example (New)

Example_new an example of creating Uint128 values.

fmt.Println(bigx.Uint128{Lo: 12345})

Output:

12345

Index

• type Uint128
  • func Max128() Uint128
  • func One128() Uint128
  • func Zero128() Uint128
• type Uint256
  • func Max256() Uint256
  • func One256() Uint256
  • func Zero256() Uint256

Examples

• Package (New)

Types

type Uint128

type Uint128 = u128.Uint128

Uint128 is type alias for 128-bit unsigned integer.

func Max128

func Max128() Uint128

Max128 is the largest possible Uint128 value.

func One128

func One128() Uint128

One128 is the lowest non-zero Uint128 value.

func Zero128

func Zero128() Uint128

Zero128 is the lowest possible Uint128 value.

type Uint256

type Uint256 = u256.Uint256

Uint256 is type alias for 256-bit unsigned integer.

func Max256

func Max256() Uint256

Max256 is the largest possible Uint256 value.

func One256

func One256() Uint256

One256 is the lowest non-zero Uint256 value.

func Zero256

func Zero256() Uint256

Zero256 is the lowest possible Uint256 value.