uint128

package module
v1.1.1-0...-8615506 Latest Latest
Warning

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

 Go to latest Published: Mar 12, 2021 License: MIT Imports: 6 Imported by: 0

README

uint128

GoDoc Go Report Card

go get github.com/Pilatuz/uint128

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 corresponding big.Int.Format) implementation of Format method to support for example hex output as fmt.Sprintf("%X", u).
  • Store/Load methods in little-endian and big-endian byte order.
  • New Not and AndNot methods.

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

The name uint128.Uint128 stutters, so I recommend either using a "dot import" or aliasing uint128.Uint128 to give it a project-specific name. Embedding the type is not recommended, because methods will still return uint128.Uint128; this means that, if you want to extend the type with new methods, your best bet is probably to copy the source code wholesale and rename the identifier. ¯\_(ツ)_/¯

Benchmarks

Addition, multiplication, and subtraction are on par with their native 64-bit equivalents. Division is slower: ~20x slower when dividing a Uint128 by a uint64, and ~100x slower when dividing by a Uint128. However, division is still faster than with big.Int (for the same operands), especially when dividing by a uint64.

BenchmarkArithmetic/Add-4              2000000000    0.45 ns/op    0 B/op      0 allocs/op
BenchmarkArithmetic/Sub-4              2000000000    0.67 ns/op    0 B/op      0 allocs/op
BenchmarkArithmetic/Mul-4              2000000000    0.42 ns/op    0 B/op      0 allocs/op
BenchmarkArithmetic/Lsh-4              2000000000    1.06 ns/op    0 B/op      0 allocs/op
BenchmarkArithmetic/Rsh-4              2000000000    1.06 ns/op    0 B/op      0 allocs/op

BenchmarkDivision/native_64/64-4       2000000000    0.39 ns/op    0 B/op      0 allocs/op
BenchmarkDivision/Div_128/64-4         2000000000    6.28 ns/op    0 B/op      0 allocs/op
BenchmarkDivision/Div_128/128-4        30000000      45.2 ns/op    0 B/op      0 allocs/op
BenchmarkDivision/big.Int_128/64-4     20000000      98.2 ns/op    8 B/op      1 allocs/op
BenchmarkDivision/big.Int_128/128-4    30000000      53.4 ns/op    48 B/op     1 allocs/op

BenchmarkString/Uint128-4              10000000      173 ns/op     48 B/op     1 allocs/op
BenchmarkString/big.Int-4              5000000       350 ns/op     144 B/op    3 allocs/op

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func StoreUint128BE 

func StoreUint128BE(b []byte, u Uint128)

StoreUint128BE stores 128-bit value in byte slice in big-endian order. It panics if byte slice length is less than 16.

func StoreUint128LE 

func StoreUint128LE(b []byte, u Uint128)

StoreUint128LE stores 128-bit value in byte slice in little-endian order. It panics if byte slice length is less than 16.

Types

type Uint128 

type Uint128 struct {
	Lo uint64 // lower 64-bit half
	Hi uint64 // higher 64-bit half
}

Uint128 is an unsigned 128-bit number. All methods are immutable, works just like standard uint64.

func From64 

func From64(v uint64) Uint128

From64 converts 64-bit value v to a Uint128 value. Higher 64-bit half will be zero.

func FromBig 

func FromBig(i *big.Int) Uint128

FromBig converts *big.Int to 128-bit Uint128 value ignoring overflows. If input integer is nil or negative then return Zero. If input interger overflows 128-bit then return Max.

func FromBigX 

func FromBigX(i *big.Int) (Uint128, bool)

FromBigX converts *big.Int to 128-bit Uint128 value (eXtended version). Provides ok successful flag as a second return value. If input integer is negative or overflows 128-bit then ok=false. If input if nil then zero 128-bit returned.

func LoadUint128BE 

func LoadUint128BE(b []byte) Uint128

LoadUint128BE loads 128-bit value from byte slice in big-endian order. It panics if byte slice length is less than 16.

func LoadUint128LE 

func LoadUint128LE(b []byte) Uint128

LoadUint128LE loads 128-bit value from byte slice in little-endian order. It panics if byte slice length is less than 16.

func Max 

func Max() Uint128

Max is the largest possible Uint128 value.

func One 

func One() Uint128

One is the lowest non-zero Uint128 value.

func Zero 

func Zero() Uint128

Zero is the lowest possible Uint128 value.

func (Uint128) Add 

func (u Uint128) Add(v Uint128) Uint128

Add returns sum (u+v) of two 128-bit values. Wrap-around semantic is used here: Max().Add(From64(1)) == Zero()

func (Uint128) Add64 

func (u Uint128) Add64(v uint64) Uint128

Add64 returns sum u+v of 128-bit and 64-bit values. Wrap-around semantic is used here: Max().Add64(1) == Zero()

func (Uint128) And 

func (u Uint128) And(v Uint128) Uint128

And returns logical AND (u&v) of two 128-bit values.

func (Uint128) And64 

func (u Uint128) And64(v uint64) Uint128

And64 returns logical AND (u&v) of 128-bit and 64-bit values.

func (Uint128) AndNot 

func (u Uint128) AndNot(v Uint128) Uint128

AndNot returns logical AND NOT (u&^v) of two 128-bit values.

func (Uint128) AndNot64 

func (u Uint128) AndNot64(v uint64) Uint128

AndNot64 returns logical AND NOT (u&v) of 128-bit and 64-bit values.

func (Uint128) Big 

func (u Uint128) Big() *big.Int

Big returns 128-bit value as a *big.Int.

func (Uint128) BitLen 

func (u Uint128) BitLen() int

BitLen returns the minimum number of bits required to represent 128-bit value. The result is 0 for u == 0.

func (Uint128) Cmp 

func (u Uint128) Cmp(v Uint128) int

Cmp compares two 128-bit values and returns: 

-1 if u <  v
 0 if u == v
+1 if u >  v

func (Uint128) Cmp64 

func (u Uint128) Cmp64(v uint64) int

Cmp64 compares 128-bit and 64-bit values and returns: 

-1 if u <  v
 0 if u == v
+1 if u >  v

func (Uint128) Div 

func (u Uint128) Div(v Uint128) Uint128

Div returns division (u/v) of two 128-bit values.

func (Uint128) Div64 

func (u Uint128) Div64(v uint64) Uint128

Div64 returns division (u/v) of 128-bit and 64-bit values.

func (Uint128) Equals 

func (u Uint128) Equals(v Uint128) bool

Equals returns true if two 128-bit values are equal. Uint128 values can be compared directly with == operator but use of the Equals method is preferred for consistency.

func (Uint128) Equals64 

func (u Uint128) Equals64(v uint64) bool

Equals64 returns true if 128-bit value equals to a 64-bit value.

func (Uint128) Format 

func (u Uint128) Format(s fmt.State, ch rune)

Format does custom formatting of 128-bit value.

func (Uint128) IsZero 

func (u Uint128) IsZero() bool

IsZero returns true if stored 128-bit value is zero.

func (Uint128) LeadingZeros 

func (u Uint128) LeadingZeros() int

LeadingZeros returns the number of leading zero bits. The result is 128 for u == 0.

func (Uint128) Lsh 

func (u Uint128) Lsh(n uint) Uint128

Lsh returns left shift (u<<n).

func (Uint128) Mod 

func (u Uint128) Mod(v Uint128) Uint128

Mod returns modulo (u%v) of two 128-bit values.

func (Uint128) Mod64 

func (u Uint128) Mod64(v uint64) uint64

Mod64 returns modulo (u%v) of 128-bit and 64-bit values.

func (Uint128) Mul 

func (u Uint128) Mul(v Uint128) Uint128

Mul returns multiplication (u*v) of two 128-bit values. Wrap-around semantic is used here: Max().Mul(Max()) == From64(1).

func (Uint128) Mul64 

func (u Uint128) Mul64(v uint64) Uint128

Mul64 returns multiplication (u*v) of 128-bit and 64-bit values. Wrap-around semantic is used here: Max().Mul64(2) == Max().Sub64(1).

func (Uint128) Not 

func (u Uint128) Not() Uint128

Not returns logical NOT (^u) of 128-bit value.

func (Uint128) OnesCount 

func (u Uint128) OnesCount() int

OnesCount returns the number of one bits ("population count").

func (Uint128) Or 

func (u Uint128) Or(v Uint128) Uint128

Or returns logical OR (u|v) of two 128-bit values.

func (Uint128) Or64 

func (u Uint128) Or64(v uint64) Uint128

Or64 returns logical OR (u|v) of 128-bit and 64-bit values.

func (Uint128) QuoRem 

func (u Uint128) QuoRem(v Uint128) (Uint128, Uint128)

QuoRem returns quotient (u/v) and remainder (u%v) of two 128-bit values.

func (Uint128) QuoRem64 

func (u Uint128) QuoRem64(v uint64) (Uint128, uint64)

QuoRem64 returns quotient (u/v) and remainder (u%v) of 128-bit and 64-bit values.

func (Uint128) Reverse 

func (u Uint128) Reverse() Uint128

Reverse returns the value with bits in reversed order.

func (Uint128) ReverseBytes 

func (u Uint128) ReverseBytes() Uint128

ReverseBytes returns the value with bytes in reversed order.

func (Uint128) RotateLeft 

func (u Uint128) RotateLeft(k int) Uint128

RotateLeft returns the value of u rotated left by (k mod 128) bits.

func (Uint128) RotateRight 

func (u Uint128) RotateRight(k int) Uint128

RotateRight returns the value of u rotated left by (k mod 128) bits.

func (Uint128) Rsh 

func (u Uint128) Rsh(n uint) Uint128

Rsh returns right shift (u>>n).

func (Uint128) String 

func (u Uint128) String() string

String returns the base-10 representation of 128-bit value.

func (Uint128) Sub 

func (u Uint128) Sub(v Uint128) Uint128

Sub returns difference (u-v) of two 128-bit values. Wrap-around semantic is used here: Zero().Sub(From64(1)) == Max().

func (Uint128) Sub64 

func (u Uint128) Sub64(v uint64) Uint128

Sub64 returns difference (u-v) of 128-bit and 64-bit values. Wrap-around semantic is used here: Zero().Sub64(1) == Max().

func (Uint128) TrailingZeros 

func (u Uint128) TrailingZeros() int

TrailingZeros returns the number of trailing zero bits. The result is 128 for u == 0.

func (Uint128) Xor 

func (u Uint128) Xor(v Uint128) Uint128

Xor returns logical XOR (u^v) of two 128-bit values.

func (Uint128) Xor64 

func (u Uint128) Xor64(v uint64) Uint128

Xor64 returns logical XOR (u^v) of 128-bit and 64-bit values.

Source Files

View all Source files

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.