uint128

package module
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Apr 12, 2024 License: MIT Imports: 6 Imported by: 0

README

uint128

go get github.com/gaze-network/uint128

This project is a fork of lukechampine/uint128 with additional features and improvements:

  1. Change overflow behavior from panicking to returning whether the operation overflowed.
    • Add AddOverflow, Add64Overflow, SubOverflow, Sub64Overflow, MulOverflow, Mul64Overflow functions which returns additional boolean indicating whether the operation overflowed. The original functions now ignores overflow instead of panicking.
    • Change FromBig function behaviour to return errors instead of panicking.
  2. Add conversion functions Uint64(), Uint32(), Uint16(), Uint8() to convert Uint128 to native types.
  3. Add functions IsUint64(), IsUint32(), IsUint16(), IsUint8() to check if Uint128 can be converted to native types without overflow.

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 (
	ErrValueNegative = errors.New("value cannot be negative")
	ErrValueOverflow = errors.New("value overflows Uint128")
)
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, err error)

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 

func FromBytesBE(b []byte) Uint128

FromBytesBE converts big-endian b to a Uint128 value.

func FromString 

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. If the result overflows, it is ignored.

func (Uint128) Add64 

func (u Uint128) Add64(v uint64) Uint128

Add64 returns u+v. If the result overflows, it is ignored.

func (Uint128) Add64Overflow 

func (u Uint128) Add64Overflow(v uint64) (Uint128, bool)

Add64 returns u+v. The second return value is true if the result overflows.

func (Uint128) AddOverflow 

func (u Uint128) AddOverflow(v Uint128) (Uint128, bool)

Add returns u+v. The second return value is true if the result overflows.

func (Uint128) AddWrap 

func (u Uint128) AddWrap(v Uint128) Uint128

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

func (Uint128) AddWrap64 

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) IsUint16 added in v1.2.0 

func (u Uint128) IsUint16() bool

Uint returns true if u can be safely represented as a uint16.

func (Uint128) IsUint32 added in v1.2.0 

func (u Uint128) IsUint32() bool

Uint returns true if u can be safely represented as a uint32.

func (Uint128) IsUint64 added in v1.2.0 

func (u Uint128) IsUint64() bool

Uint returns true if u can be safely represented as a uint64.

func (Uint128) IsUint8 added in v1.2.0 

func (u Uint128) IsUint8() bool

Uint returns true if u can be safely represented as a uint8.

func (Uint128) IsZero 

func (u Uint128) IsZero() bool

IsZero returns true if u == 0.

func (Uint128) LeadingZeros 

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 

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) MarshalJSON added in v1.3.0 

func (u Uint128) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (Uint128) MarshalText added in v1.3.0 

func (u Uint128) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Uint128) Mod 

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

Mod returns r = u%v.

func (Uint128) Mod64 

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. If the result overflows, it is ignored.

func (Uint128) Mul64 

func (u Uint128) Mul64(v uint64) Uint128

Mul64 returns u*v. If the result overflows, it is ignored.

func (Uint128) Mul64Overflow 

func (u Uint128) Mul64Overflow(v uint64) (Uint128, bool)

Mul64 returns u*v, panicking on overflow.

func (Uint128) MulOverflow 

func (u Uint128) MulOverflow(v Uint128) (Uint128, bool)

Mul returns u*v, panicking on overflow.

func (Uint128) MulWrap 

func (u Uint128) MulWrap(v Uint128) Uint128

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

func (Uint128) MulWrap64 

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 

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 

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 

func (u Uint128) Reverse() Uint128

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

func (Uint128) ReverseBytes 

func (u Uint128) ReverseBytes() Uint128

ReverseBytes returns the value of u with its 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) (s Uint128)

Rsh returns u>>n.

func (*Uint128) Scan 

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. If the result underflows, it is ignored.

func (Uint128) Sub64 

func (u Uint128) Sub64(v uint64) Uint128

Sub64 returns u-v. If the result underflows, it is ignored.

func (Uint128) Sub64Overflow 

func (u Uint128) Sub64Overflow(v uint64) (Uint128, bool)

Sub64 returns u-v. The second return value is true if the result underflows.

func (Uint128) SubOverflow 

func (u Uint128) SubOverflow(v Uint128) (Uint128, bool)

Sub returns u-v. The second return value is true if the result underflows.

func (Uint128) SubWrap 

func (u Uint128) SubWrap(v Uint128) Uint128

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

func (Uint128) SubWrap64 

func (u Uint128) SubWrap64(v uint64) Uint128

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

func (Uint128) TrailingZeros 

func (u Uint128) TrailingZeros() int

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

func (Uint128) Uint16 added in v1.1.0 

func (u Uint128) Uint16() uint16

Uint16 returns the lower 16 bits of u.

func (Uint128) Uint32 added in v1.1.0 

func (u Uint128) Uint32() uint32

Uint32 returns the lower 32 bits of u.

func (Uint128) Uint64 added in v1.1.0 

func (u Uint128) Uint64() uint64

Uint64 returns the lower 64 bits of u.

func (Uint128) Uint8 added in v1.1.0 

func (u Uint128) Uint8() uint8

Uint8 returns the lower 8 bits of u.

func (*Uint128) UnmarshalJSON added in v1.3.0 

func (u *Uint128) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*Uint128) UnmarshalText added in v1.3.0 

func (u *Uint128) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

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.