README
¶
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 ¶
- Variables
- type Uint128
- func (u Uint128) Add(v Uint128) Uint128
- func (u Uint128) Add64(v uint64) Uint128
- func (u Uint128) AddWrap(v Uint128) Uint128
- func (u Uint128) AddWrap64(v uint64) Uint128
- func (u Uint128) And(v Uint128) Uint128
- func (u Uint128) And64(v uint64) Uint128
- func (u Uint128) Big() *big.Int
- func (u Uint128) Cmp(v Uint128) int
- func (u Uint128) Cmp64(v uint64) int
- func (u Uint128) Div(v Uint128) Uint128
- func (u Uint128) Div64(v uint64) Uint128
- func (u Uint128) Equals(v Uint128) bool
- func (u Uint128) Equals64(v uint64) bool
- func (u Uint128) IsZero() bool
- func (u Uint128) LeadingZeros() int
- func (u Uint128) Len() int
- func (u Uint128) Lsh(n uint) (s Uint128)
- func (u Uint128) Mod(v Uint128) (r Uint128)
- func (u Uint128) Mod64(v uint64) (r uint64)
- func (u Uint128) Mul(v Uint128) Uint128
- func (u Uint128) Mul64(v uint64) Uint128
- func (u Uint128) MulWrap(v Uint128) Uint128
- func (u Uint128) MulWrap64(v uint64) Uint128
- func (u Uint128) OnesCount() int
- func (u Uint128) Or(v Uint128) Uint128
- func (u Uint128) Or64(v uint64) Uint128
- func (u Uint128) PutBytes(b []byte)
- func (u Uint128) QuoRem(v Uint128) (q, r Uint128)
- func (u Uint128) QuoRem64(v uint64) (q Uint128, r uint64)
- func (u Uint128) Reverse() Uint128
- func (u Uint128) ReverseBytes() Uint128
- func (u Uint128) RotateLeft(k int) Uint128
- func (u Uint128) RotateRight(k int) Uint128
- func (u Uint128) Rsh(n uint) (s Uint128)
- func (u *Uint128) Scan(s fmt.ScanState, ch rune) error
- func (u Uint128) String() string
- func (u Uint128) Sub(v Uint128) Uint128
- func (u Uint128) Sub64(v uint64) Uint128
- func (u Uint128) SubWrap(v Uint128) Uint128
- func (u Uint128) SubWrap64(v uint64) Uint128
- func (u Uint128) TrailingZeros() int
- func (u Uint128) Xor(v Uint128) Uint128
- func (u Uint128) Xor64(v uint64) Uint128
Constants ¶
This section is empty.
Variables ¶
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 FromBig ¶
FromBig converts i to a Uint128 value. It panics if i is negative or overflows 128 bits.
func FromString ¶
FromString parses s as a Uint128 value.
func (Uint128) AddWrap ¶
AddWrap returns u+v with wraparound semantics; for example, Max.AddWrap(From64(1)) == Zero.
func (Uint128) AddWrap64 ¶
AddWrap64 returns u+v with wraparound semantics; for example, Max.AddWrap64(1) == Zero.
func (Uint128) Equals ¶
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) LeadingZeros ¶
LeadingZeros returns the number of leading zero bits in u; the result is 128 for u == 0.
func (Uint128) Len ¶
Len returns the minimum number of bits required to represent u; the result is 0 for u == 0.
func (Uint128) MulWrap ¶
MulWrap returns u*v with wraparound semantics; for example, Max.MulWrap(Max) == 1.
func (Uint128) MulWrap64 ¶
MulWrap64 returns u*v with wraparound semantics; for example, Max.MulWrap64(2) == Max.Sub64(1).
func (Uint128) ReverseBytes ¶
ReverseBytes returns the value of u with its bytes in reversed order.
func (Uint128) RotateLeft ¶
RotateLeft returns the value of u rotated left by (k mod 128) bits.
func (Uint128) RotateRight ¶
RotateRight returns the value of u rotated left by (k mod 128) bits.
func (Uint128) SubWrap ¶
SubWrap returns u-v with wraparound semantics; for example, Zero.SubWrap(From64(1)) == Max.
func (Uint128) SubWrap64 ¶
SubWrap64 returns u-v with wraparound semantics; for example, Zero.SubWrap64(1) == Max.
func (Uint128) TrailingZeros ¶
TrailingZeros returns the number of trailing zero bits in u; the result is 128 for u == 0.
Source Files