uint128

package module
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 13, 2023 License: MIT Imports: 6 Imported by: 35

README

uint128

GoDoc Go Report Card

go get lukechampine.com/uint128

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

View Source 
var Max = New(math.MaxUint64, math.MaxUint64)

Max is the largest possible uint128 value.

Functions

This section is empty.

Types

type Uint128 

type Uint128 struct {
	Lo, Hi uint64
}

A Uint128 is an unsigned 128-bit number. 

var Zero Uint128

Zero is a zero-valued uint128.

func From64 

func From64(v uint64) Uint128

From64 converts v to a Uint128 value.

func FromBig 

func FromBig(i *big.Int) (u Uint128)

FromBig converts i to a Uint128 value. It panics if i is negative or overflows 128 bits.

func FromBytes 

func FromBytes(b []byte) Uint128

FromBytes converts b to a Uint128 value.

func FromBytesBE added in v1.3.0 

func FromBytesBE(b []byte) Uint128

FromBytesBE converts big-endian b to a Uint128 value.

func FromString added in v1.2.0 

func FromString(s string) (u Uint128, err error)

FromString parses s as a Uint128 value.

func New 

func New(lo, hi uint64) Uint128

New returns the Uint128 value (lo,hi).

func (Uint128) Add 

func (u Uint128) Add(v Uint128) Uint128

Add returns u+v.

func (Uint128) Add64 

func (u Uint128) Add64(v uint64) Uint128

Add64 returns u+v.

func (Uint128) AddWrap added in v1.1.0 

func (u Uint128) AddWrap(v Uint128) Uint128

AddWrap returns u+v with wraparound semantics; for example, Max.AddWrap(From64(1)) == Zero.

func (Uint128) AddWrap64 added in v1.1.0 

func (u Uint128) AddWrap64(v uint64) Uint128

AddWrap64 returns u+v with wraparound semantics; for example, Max.AddWrap64(1) == Zero.

func (Uint128) And 

func (u Uint128) And(v Uint128) Uint128

And returns u&v.

func (Uint128) And64 

func (u Uint128) And64(v uint64) Uint128

And64 returns u&v.

func (Uint128) Big 

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

Big returns u as a *big.Int.

func (Uint128) Cmp 

func (u Uint128) Cmp(v Uint128) int

Cmp compares u and v 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 u and v 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 u/v.

func (Uint128) Div64 

func (u Uint128) Div64(v uint64) Uint128

Div64 returns u/v.

func (Uint128) Equals 

func (u Uint128) Equals(v Uint128) bool

Equals returns true if u == v.

Uint128 values can be compared directly with ==, but use of the Equals method is preferred for consistency.

func (Uint128) Equals64 

func (u Uint128) Equals64(v uint64) bool

Equals64 returns true if u == v.

func (Uint128) IsZero 

func (u Uint128) IsZero() bool

IsZero returns true if u == 0.

func (Uint128) LeadingZeros added in v1.1.0 

func (u Uint128) LeadingZeros() int

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

func (Uint128) Len added in v1.1.0 

func (u Uint128) Len() int

Len returns the minimum number of bits required to represent u; the result is 0 for u == 0.

func (Uint128) Lsh 

func (u Uint128) Lsh(n uint) (s Uint128)

Lsh returns u<<n.

func (Uint128) Mod added in v1.1.0 

func (u Uint128) Mod(v Uint128) (r Uint128)

Mod returns r = u%v.

func (Uint128) Mod64 added in v1.1.0 

func (u Uint128) Mod64(v uint64) (r uint64)

Mod64 returns r = u%v.

func (Uint128) Mul 

func (u Uint128) Mul(v Uint128) Uint128

Mul returns u*v, panicking on overflow.

func (Uint128) Mul64 

func (u Uint128) Mul64(v uint64) Uint128

Mul64 returns u*v, panicking on overflow.

func (Uint128) MulWrap added in v1.1.0 

func (u Uint128) MulWrap(v Uint128) Uint128

MulWrap returns u*v with wraparound semantics; for example, Max.MulWrap(Max) == 1.

func (Uint128) MulWrap64 added in v1.1.0 

func (u Uint128) MulWrap64(v uint64) Uint128

MulWrap64 returns u*v with wraparound semantics; for example, Max.MulWrap64(2) == Max.Sub64(1).

func (Uint128) OnesCount added in v1.1.0 

func (u Uint128) OnesCount() int

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

func (Uint128) Or 

func (u Uint128) Or(v Uint128) Uint128

Or returns u|v.

func (Uint128) Or64 

func (u Uint128) Or64(v uint64) Uint128

Or64 returns u|v.

func (Uint128) PutBytes 

func (u Uint128) PutBytes(b []byte)

PutBytes stores u in b in little-endian order. It panics if len(b) < 16.

func (Uint128) PutBytesBE added in v1.3.0 

func (u Uint128) PutBytesBE(b []byte)

PutBytesBE stores u in b in big-endian order. It panics if len(ip) < 16.

func (Uint128) QuoRem 

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

QuoRem returns q = u/v and r = u%v.

func (Uint128) QuoRem64 

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

QuoRem64 returns q = u/v and r = u%v.

func (Uint128) Reverse added in v1.1.0 

func (u Uint128) Reverse() Uint128

Reverse returns the value of u with its bits in reversed order.

func (Uint128) ReverseBytes added in v1.1.0 

func (u Uint128) ReverseBytes() Uint128

ReverseBytes returns the value of u with its bytes in reversed order.

func (Uint128) RotateLeft added in v1.1.0 

func (u Uint128) RotateLeft(k int) Uint128

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

func (Uint128) RotateRight added in v1.1.0 

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) (s Uint128)

Rsh returns u>>n.

func (*Uint128) Scan added in v1.2.0 

func (u *Uint128) Scan(s fmt.ScanState, ch rune) error

Scan implements fmt.Scanner.

func (Uint128) String 

func (u Uint128) String() string

String returns the base-10 representation of u as a string.

func (Uint128) Sub 

func (u Uint128) Sub(v Uint128) Uint128

Sub returns u-v.

func (Uint128) Sub64 

func (u Uint128) Sub64(v uint64) Uint128

Sub64 returns u-v.

func (Uint128) SubWrap added in v1.1.0 

func (u Uint128) SubWrap(v Uint128) Uint128

SubWrap returns u-v with wraparound semantics; for example, Zero.SubWrap(From64(1)) == Max.

func (Uint128) SubWrap64 added in v1.1.0 

func (u Uint128) SubWrap64(v uint64) Uint128

SubWrap64 returns u-v with wraparound semantics; for example, Zero.SubWrap64(1) == Max.

func (Uint128) TrailingZeros added in v1.1.0 

func (u Uint128) TrailingZeros() int

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

func (Uint128) Xor 

func (u Uint128) Xor(v Uint128) Uint128

Xor returns u^v.

func (Uint128) Xor64 

func (u Uint128) Xor64(v uint64) Uint128

Xor64 returns u^v.

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.