cmp.gno

  1// cmp (or, comparisons) includes methods for comparing Uint instances.
  2// These comparison functions cover a range of operations including equality checks, less than/greater than
  3// evaluations, and specialized comparisons such as signed greater than. These are fundamental for logical
  4// decision making based on Uint values.
  5package uint256
  6
  7import "math/bits"
  8
  9// Cmp compares z and x and returns -1 if z < x, 0 if z == x, or +1 if z > x.
 10//
 11// Parameters:
 12//   - x: the Uint value compared with z
 13//
 14// Returns:
 15//   - r: -1 when z<x, 0 when z==x, or +1 when z>x
 16func (z *Uint) Cmp(x *Uint) (r int) {
 17	// z < x <=> z - x < 0 i.e. when subtraction overflows.
 18	d0, carry := bits.Sub64(z[0], x[0], 0)
 19	d1, carry := bits.Sub64(z[1], x[1], carry)
 20	d2, carry := bits.Sub64(z[2], x[2], carry)
 21	d3, carry := bits.Sub64(z[3], x[3], carry)
 22	if carry == 1 {
 23		return -1
 24	}
 25	if d0|d1|d2|d3 == 0 {
 26		return 0
 27	}
 28	return 1
 29}
 30
 31// IsZero returns true if z equals 0.
 32//
 33// Returns:
 34//   - isZero: true when all four words of z are zero
 35func (z *Uint) IsZero() bool {
 36	return (z[0] | z[1] | z[2] | z[3]) == 0
 37}
 38
 39// Sign returns the sign of z interpreted as a two's complement signed number.
 40// It returns -1 if z < 0, 0 if z == 0, or +1 if z > 0.
 41//
 42// Returns:
 43//   - sign: -1, 0, or +1 according to z interpreted as a two's-complement signed value
 44func (z *Uint) Sign() int {
 45	if z.IsZero() {
 46		return 0
 47	}
 48	if z[3] < 0x8000000000000000 {
 49		return 1
 50	}
 51	return -1
 52}
 53
 54// Lt returns true if z is less than x.
 55//
 56// Parameters:
 57//   - x: the comparison operand
 58//
 59// Returns:
 60//   - less: true when z<x
 61func (z *Uint) Lt(x *Uint) bool {
 62	// z < x <=> z - x < 0 i.e. when subtraction overflows.
 63	_, carry := bits.Sub64(z[0], x[0], 0)
 64	_, carry = bits.Sub64(z[1], x[1], carry)
 65	_, carry = bits.Sub64(z[2], x[2], carry)
 66	_, carry = bits.Sub64(z[3], x[3], carry)
 67
 68	return carry != 0
 69}
 70
 71// Gt returns true if z is greater than x.
 72//
 73// Parameters:
 74//   - x: the comparison operand
 75//
 76// Returns:
 77//   - greater: true when z>x
 78func (z *Uint) Gt(x *Uint) bool {
 79	return x.Lt(z)
 80}
 81
 82// Lte returns true if z is less than or equal to x.
 83//
 84// Parameters:
 85//   - x: the comparison operand
 86//
 87// Returns:
 88//   - lessOrEqual: true when z<=x
 89func (z *Uint) Lte(x *Uint) bool {
 90	return !x.Lt(z)
 91}
 92
 93// Gte returns true if z is greater than or equal to x.
 94//
 95// Parameters:
 96//   - x: the comparison operand
 97//
 98// Returns:
 99//   - greaterOrEqual: true when z>=x
100func (z *Uint) Gte(x *Uint) bool {
101	return !z.Lt(x)
102}
103
104// Eq returns true if z equals x.
105//
106// Parameters:
107//   - x: the comparison operand
108//
109// Returns:
110//   - equal: true when z and x have identical 256-bit values
111func (z *Uint) Eq(x *Uint) bool {
112	return (z[0] == x[0]) && (z[1] == x[1]) && (z[2] == x[2]) && (z[3] == x[3])
113}
114
115// Neq returns true if z does not equal x.
116//
117// Parameters:
118//   - x: the comparison operand
119//
120// Returns:
121//   - notEqual: true when z and x differ
122func (z *Uint) Neq(x *Uint) bool {
123	return !z.Eq(x)
124}