compare

package
v0.35.0 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: Apache-2.0 Imports: 6 Imported by: 7

README

compare

Comparison helpers for values of different or unknown data types. Interface(a, b) coerces two arbitrary values to a common kind and returns -1/0/1; WithOperator(a, op, b) evaluates a named operator (greater-than, contains, begins-with, …) to a bool. Typed helpers (Int/Int8/…/Int64, Float32/Float64, String, BeginsWith, Contains, EndsWith) cover the known-type cases. Part of rosetta.

Go Reference

What matters here

  • A bool on either side coerces the other operand to bool, and this runs before the numeric block. Interface(true, 1) and Interface(1, true) both succeed symmetrically, and a bool is never treated as a number. Know this before comparing mixed bool/number data — the bool wins.
  • Numbers compare on a common numeric kind, not per-type-pair. Any signed/unsigned/float combination is handled symmetrically through a single numeric path, so you don't get spurious "incompatible types" between, say, an int and a float64.
  • Incompatible types return an error, not a silent 0. Interface (and WithOperator) return a non-nil error when the two values can't be coerced to a common comparable kind — callers must check it rather than assuming 0 means "equal".
  • BeginsWith/Contains/EndsWith are substring operators handled outside the ordering path (see WithOperator). They answer a containment question, not a -1/0/1 ordering, so they're routed before the Interface coercion runs.

This package works around Go's pre-generics comparison gaps and will likely shrink as the standard library grows; lean on the typed helpers when the type is known and reserve Interface for genuinely dynamic data.

Documentation

Overview

Package compare provides functions for comparing values of arbitrary types.

The concrete helpers (Int, String, Float64, and their siblings) return the usual three-way result: negative, zero, or positive. Interface compares two values of unknown type by promoting them to a common base type, and the predicate helpers built on it — Equal, GreaterThan, Contains, BeginsWith, EndsWith, and friends — are what higher-level packages use to evaluate filter expressions. The Operator constants name those predicates as strings, so a query language can be parsed straight into a comparison.

Custom types opt into all of this by implementing one of the small interfaces in interfaces.go: Booler, Inter, Floater, Stringer, Hexer, LengthGetter, Nuller, or ContainsInterfacer. IsZero consults them in a fixed order, which is why a null.Int reports as zero through its Nuller implementation rather than through its numeric value.

Index

Constants

View Source 
const OperatorBeginsWith = "BEGINS"

OperatorBeginsWith represents a "begins with" comparison , when used in Predicates and Criteria. It is only valid for string values.

View Source 
const OperatorContainedBy = "CONTAINED BY"

OperatorContainedBy represents a "contains" comparison in reverse, when used in Predicates and Criteria. It is only valid for string values.

View Source 
const OperatorContains = "CONTAINS"

OperatorContains represents a "contains" comparison, when used in Predicates and Criteria. It is only valid for string values.

View Source 
const OperatorEndsWith = "ENDS"

OperatorEndsWith represents a "ends with" comparison, when used in Predicates and Criteria. It is only valid for string values.

View Source 
const OperatorEqual = "="

OperatorEqual represents an "equals" comparison, when used in Predicates and Criteria

View Source 
const OperatorGreaterOrEqual = ">="

OperatorGreaterOrEqual represents an "greater or equal" comparison, when used in Predicates and Criteria

View Source 
const OperatorGreaterThan = ">"

OperatorGreaterThan represents an "greater than" comparison, when used in Predicates and Criteria

View Source 
const OperatorLessOrEqual = "<="

OperatorLessOrEqual represents an "less or equal" comparison, when used in Predicates and Criteria

View Source 
const OperatorLessThan = "<"

OperatorLessThan represents a "less than" comparison, when used in Predicates and Criteria

View Source 
const OperatorNotEqual = "!="

OperatorNotEqual represents a "not equals" comparison, when used in Predicates and Criteria

Variables

This section is empty.

Functions

func BeginsWith 

func BeginsWith(value1 any, value2 any) bool

BeginsWith is a simple "generic-safe" function for string comparison. It returns TRUE if value1 begins with value2

func Bool added in v0.13.1 

func Bool(value1 bool, value2 bool) int

Bool compares two bool values, ordering FALSE before TRUE. It returns -1 if value1 is LESS THAN value2 (false < true). It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2 (true > false).

func Contains 

func Contains(value1 any, value2 any) bool

Contains is a simple "generic-safe" function for string comparison. It returns TRUE if value1 contains value2

func EndsWith 

func EndsWith(value1 any, value2 any) bool

EndsWith is a simple "generic-safe" function for string comparison. It returns TRUE if value1 ends with value2

func Equal 

func Equal(value1 any, value2 any) bool

Equal is a simplified version of Compare. It ONLY returns true if the two provided values are EQUAL. In all other cases (including errors) it returns FALSE

func Float32 

func Float32(value1 float32, value2 float32) int

Float32 compares two float32 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func Float64 

func Float64(value1 float64, value2 float64) int

Float64 compares two float64 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func GreaterThan 

func GreaterThan(value1 any, value2 any) bool

GreaterThan is a simplified version of Compare. It ONLY returns true if value1 is verifiably GREATER THAN value2. In all other cases (including errors) it returns FALSE

func Int 

func Int(value1 int, value2 int) int

Int compares two int values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func Int8 

func Int8(value1 int8, value2 int8) int

Int8 compares two int8 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func Int16 

func Int16(value1 int16, value2 int16) int

Int16 compares two int16 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func Int32 

func Int32(value1 int32, value2 int32) int

Int32 compares two int32 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func Int64 

func Int64(value1 int64, value2 int64) int

Int64 compares two int64 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func Interface 

func Interface(value1 any, value2 any) (int, error)

Interface tries its best to muscle value1 and value2 into compatible types so that they can be compared. If value1 is LESS THAN value2, it returns -1, nil If value1 is EQUAL TO value2, it returns 0, nil If value1 is GREATER THAN value2, it returns 1, nil If the two values are not compatible, then it returns 0, [DERP] with an explanation of the error. Numeric values are compared across every signed, unsigned, and floating-point combination; strings and Stringers are compared lexically. Other types (and mismatched non-numeric types) are incompatible.

func IsNil added in v0.19.0 

func IsNil(value any) bool

IsNil returns TRUE if the provided value is nil. This uses

func IsZero added in v0.19.0 

func IsZero(value any) bool

IsZero returns TRUE if the value is the ZERO VALUE for its datatype or NIL

func LessThan 

func LessThan(value1 any, value2 any) bool

LessThan is a simplified version of Compare. It ONLY returns true if value1 is verifiably LESS THAN value2. In all other cases (including errors) it returns FALSE

func Maps added in v0.25.14 

func Maps[T comparable](a, b map[string]T) bool

Maps returns TRUE if the two maps contain exactly the same keys and values.

func NotContains added in v0.26.0 

func NotContains(value1 any, value2 any) bool

NotContains returns TRUE if value1 does not contain value2. It is the inverse of Contains.

func NotNil added in v0.19.0 

func NotNil(value any) bool

NotNil returns TRUE if the provided value is NOT nil

func NotZero added in v0.19.0 

func NotZero(value any) bool

NotZero returns TRUE if the value is NOT the zero value for its datatype

func String 

func String(value1 string, value2 string) int

String compares two string values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func UInt 

func UInt(value1 uint, value2 uint) int

UInt compares two uint values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func UInt8 

func UInt8(value1 uint8, value2 uint8) int

UInt8 compares two uint8 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func UInt16 

func UInt16(value1 uint16, value2 uint16) int

UInt16 compares two uint16 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func UInt32 

func UInt32(value1 uint32, value2 uint32) int

UInt32 compares two uint32 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func UInt64 

func UInt64(value1 uint64, value2 uint64) int

UInt64 compares two uint64 values. It returns -1 if value1 is LESS THAN value2. It returns 0 if value1 is EQUAL TO value2. It returns 1 if value1 is GREATER THAN value2.

func WithOperator 

func WithOperator(value1 any, operator string, value2 any) (bool, error)

WithOperator uses an operator to compare two values, and returns TRUE or FALSE

Types

type Booler added in v0.19.0 

type Booler interface {

	// Bool returns the float64 value of the underlying object
	Bool() bool
}

Booler interface wraps the Bool() method, that enables custom types to convert themselves to bool.

type ContainsInterfacer added in v0.25.9 

type ContainsInterfacer interface {

	// ContainsInterface returns TRUE if the underlying value is contained within the array.
	ContainsInterface(any) bool
}

ContainsInterfacer interface wraps the ContainsInterface() method, that returns TRUE if the underlying value contains the specified generic value

type Floater added in v0.19.0 

type Floater interface {

	// Float returns the float64 value of the underlying object
	Float() float64
}

Floater interface wraps the Float() method, that enables custom types to convert themselves to float64.

type Hexer added in v0.19.0 

type Hexer interface {

	// Hex returns the hexadecimal string value of the underlying object
	Hex() string
}

Hexer interface wraps the Hex() method, that enables a custom type to convert itself into a hexadecimal string

type Inter added in v0.19.0 

type Inter interface {

	// Int returns the int value of the underlying object
	Int() int
}

Inter interface wraps the Int() method, that enables custom types to convert themselves to ints.

type LengthGetter added in v0.19.0 

type LengthGetter interface {

	// Length returns the length of the array or map
	Length() int
}

LengthGetter interface wraps the Length() method, that returns the length of an array or map

type Nuller added in v0.19.0 

type Nuller interface {

	// IsNull returns TRUE if the underlying value is null
	IsNull() bool
}

Nuller wraps the IsNull interface (implemented by the null.* package) that enables custom types to declare that their value is null (zero)

type Stringer 

type Stringer interface {

	// String returns the string value of the underlying object
	String() string
}

Stringer interface wraps the String() method, that enables a custom type to convert themselves into strings.

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.