cmp

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2026 License: MIT Imports: 1 Imported by: 0

README

darvaza.org/x/cmp

Go Reference Go Report Card codecov Socket Badge

Overview

The cmp package provides generic helpers for comparing and matching values in Go. It defines type-safe comparison functions and utilities to adapt them for various use cases, leveraging Go's generics.

Interfaces

CompFunc[T any]

CompFunc is a generic comparison function type that follows the standard comparison convention:

  • Returns a negative value if a < b
  • Returns zero if a == b
  • Returns a positive value if a > b
type CompFunc[T any] func(a, b T) int

Utility functions for working with CompFunc:

  • Reverse[T any](cmp CompFunc[T]) CompFunc[T]: Creates a new comparison function that inverts the order of the original comparison.
CondFunc[T any]

CondFunc is a generic condition function type that evaluates two values and returns a boolean result:

type CondFunc[T any] func(a, b T) bool

Conversion functions:

  • AsLess[T any](cmp CompFunc[T]) CondFunc[T]: Converts a comparison function to a "less than" condition function.
  • AsEqual[T any](cmp CompFunc[T]) CondFunc[T]: Converts a comparison function to an equality condition function.
  • AsCmp[T any](less CondFunc[T]) CompFunc[T]: Converts a "less than" condition function to a comparison function. Returns -1 if less(a,b) is true, 1 if less(b,a) is true, and 0 otherwise.

Matcher

The Matcher interface provides a powerful abstraction for building composable filtering and matching logic with a fluent API. It allows for combining predicates using logical operators (AND, OR, NOT) and testing values against these conditions.

type Matcher[T any] interface {
    And(...Matcher[T]) Matcher[T]
    Or(...Matcher[T]) Matcher[T]
    Not() Matcher[T]
    Match(T) bool
}
MatchFunc

MatchFunc is a function type that implements the Matcher interface, allowing simple predicate functions to be used as matchers:

type MatchFunc[T any] func(T) bool

The MatchFunc type makes it easy to create matchers from simple functions. If a MatchFunc is nil, its Match method returns true (matches everything), making it act as a logical identity element.

Implementation Details

The package provides two concrete implementations of the Matcher interface:

  1. ands[T]: A slice-backed matcher that implements logical AND semantics

    • Returns true if all contained matchers match the value.
    • An empty ands matcher matches everything (true).

  2. ors[T]: A slice-backed matcher that implements logical OR semantics

    • Returns true if any contained matcher matches the value.
    • An empty ors matcher matches nothing (false).

Both implementations handle nil matchers gracefully by ignoring them during matching.

Utility Functions
  • AsMatcher[T any](fn MatchFunc[T]) Matcher[T]: Converts a function to a Matcher, allowing simple functions to be used with the matcher API.
  • M[T any](m Matcher[T]) func(T) bool: Converts a Matcher to a simple boolean function. If the Matcher is nil, it returns a function that always returns true.
  • MatchAny[T any](queries ...Matcher[T]) Matcher[T]: Creates a matcher that returns true if any of the provided matchers match (logical OR).
  • MatchAll[T any](queries ...Matcher[T]) Matcher[T]: Creates a matcher that returns true if all of the provided matchers match (logical AND).
Matcher Creation Functions

The package provides a comprehensive set of functions to create matchers for common comparison operations:

Equality Matchers
  • MatchEq[T comparable](v T) Matcher[T]: Creates a matcher that checks for equality with the given value.
  • MatchEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]: Creates a matcher that checks for equality using a custom comparison function.
  • MatchEqFn2[T any](v T, eq CondFunc[T]) Matcher[T]: Creates a matcher that checks for equality using a custom equality function.
Inequality Matchers
  • MatchNotEq[T comparable](v T) Matcher[T]: Creates a matcher that checks for inequality with the given value.
  • MatchNotEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]: Creates a matcher that checks for inequality using a custom comparison function.
  • MatchNotEqFn2[T any](v T, eq CondFunc[T]) Matcher[T]: Creates a matcher that checks for inequality using a custom equality function.
Greater Than Matchers
  • MatchGt[T core.Ordered](v T) Matcher[T]: Creates a matcher that checks if a value is strictly greater than the given value.
  • MatchGtFn[T any](v T, cmp CompFunc[T]) Matcher[T]: Creates a matcher that checks if a value is strictly greater than the given value using a custom comparison function.
Greater Than or Equal Matchers
  • MatchGtEq[T core.Ordered](v T) Matcher[T]: Creates a matcher that checks if a value is greater than or equal to the given value.
  • MatchGtEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]: Creates a matcher using a custom comparison function for greater than or equal checks.
  • MatchGtEqFn2[T any](v T, less CondFunc[T]) Matcher[T]: Creates a matcher using a custom condition function for greater than or equal checks.
Less Than Matchers
  • MatchLt[T core.Ordered](v T) Matcher[T]: Creates a matcher that checks if a value is strictly less than the given value.
  • MatchLtFn[T any](v T, cmp CompFunc[T]) Matcher[T]: Creates a matcher that checks if a value is strictly less than the given value using a custom comparison function.
  • MatchLtFn2[T any](v T, less CondFunc[T]) Matcher[T]: Creates a matcher that checks if a value is strictly less than the given value using a custom condition function.
Less Than or Equal Matchers
  • MatchLtEq[T core.Ordered](v T) Matcher[T]: Creates a matcher that checks if a value is less than or equal to the given value.
  • MatchLtEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]: Creates a matcher using a custom comparison function for less than or equal checks.
  • MatchLtEqFn2[T any](v T, less CondFunc[T]) Matcher[T]: Creates a matcher using a custom condition function for less than or equal checks.
Matcher Composition

The package provides a powerful composition mechanism to create matchers that operate across different types:

  • Compose[T any, V any](fn func(T) (V, bool), match Matcher[V]) Matcher[T]: Creates a new Matcher by applying an accessor function to transform input values before matching against an existing matcher.

The Compose function enables building complex matching logic by combining simpler matchers with accessor functions. The accessor function extracts or transforms a value of type T into a value of type V and indicates whether the extraction was successful. The resulting matcher returns false if the accessor function returns ok=false.

Example of Matcher Composition
type Person struct {
    Name string
    Age  int
}

// Create a matcher that checks if a person is an adult
isAdult := cmp.Compose(
    func(p Person) (int, bool) { return p.Age, true },
    cmp.MatchGtEq(18),
)

alice := Person{Name: "Alice", Age: 25}
bob := Person{Name: "Bob", Age: 16}

fmt.Println(isAdult.Match(alice))  // true
fmt.Println(isAdult.Match(bob))    // false

// Composition with conditional extraction
hasValidEmail := cmp.Compose(
    func(p Person) (string, bool) {
        // Only extract email if it contains "@"
        if strings.Contains(p.Name, "@") {
            return p.Name, true
        }
        return "", false
    },
    cmp.MatchNotEq(""),
)
More Examples
// Create matchers from predicate functions
isEven := cmp.AsMatcher(func(n int) bool { return n%2 == 0 })
isPositive := cmp.AsMatcher(func(n int) bool { return n > 0 })

// Combine matchers using logical operators
isEvenAndPositive := isEven.And(isPositive)
isEvenOrPositive := isEven.Or(isPositive)
isOdd := isEven.Not()

// Test values against matchers
fmt.Println(isEvenAndPositive.Match(4))  // true
fmt.Println(isEvenAndPositive.Match(-2)) // false
fmt.Println(isEvenOrPositive.Match(3))   // true
fmt.Println(isOdd.Match(5))              // true

Comparison Functions

The package provides several comparison functions that can be used directly or as building blocks for more complex comparisons:

Equality Functions
  • Eq[T comparable](a, b T) bool: Returns true if a equals b using Go's equality operator.
  • EqFn[T any](a, b T, cmp CompFunc[T]) bool: Returns true if a equals b using a custom comparison function.
  • EqFn2[T any](a, b T, eq CondFunc[T]) bool: Returns true if a equals b using a custom equality condition function.
Inequality Functions
  • NotEq[T comparable](a, b T) bool: Returns true if a is not equal to b using Go's inequality operator.
  • NotEqFn[T any](a, b T, cmp CompFunc[T]) bool: Returns true if a is not equal to b using a custom comparison function.
  • NotEqFn2[T any](a, b T, eq CondFunc[T]) bool: Returns true if a is not equal to b using a custom equality condition function.
Ordering Functions

  • Lt[T core.Ordered](a, b T) bool: Returns true if a is less than b.

  • LtFn[T any](a, b T, cmp CompFunc[T]) bool: Returns true if a is less than b using a custom comparison function.

  • LtFn2[T any](a, b T, less CondFunc[T]) bool: Returns true if a is less than b using a custom less-than condition function.

  • LtEq[T core.Ordered](a, b T) bool: Returns true if a is less than or equal to b.

  • LtEqFn[T any](a, b T, cmp CompFunc[T]) bool: Returns true if a is less than or equal to b using a custom comparison function.

  • LtEqFn2[T any](a, b T, less CondFunc[T]) bool: Returns true if a is less than or equal to b using a custom condition function.

  • Gt[T core.Ordered](a, b T) bool: Returns true if a is greater than b.

  • GtFn[T any](a, b T, cmp CompFunc[T]) bool: Returns true if a is greater than b using a custom comparison function.

  • GtEq[T core.Ordered](a, b T) bool: Returns true if a is greater than or equal to b.

  • GtEqFn[T any](a, b T, cmp CompFunc[T]) bool: Returns true if a is greater than or equal to b using a custom comparison function.

  • GtEqFn2[T any](a, b T, less CondFunc[T]) bool: Returns true if a is greater than or equal to b using a custom condition function.

All functions that accept custom comparison or condition functions will panic if a nil function is provided.

Development

For development guidelines, architecture notes, and AI agent instructions, see AGENTS.md.

Dependencies

This package only depends on the standard library and darvaza.org/core.

Licence

This project is licensed under the MIT Licence. See LICENCE.txt for details.

Documentation

Overview

Package cmp provides generic helpers to compare and match values. It includes functions for equality, ordering and custom comparisons, along with utilities to convert between different comparison function types.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Eq 

func Eq[T comparable](a, b T) bool

Eq returns true if a equals b for comparable types. Uses the standard Go equality operator.

func EqFn 

func EqFn[T any](a, b T, cmp CompFunc[T]) bool

EqFn returns true if a equals b using a custom comparison function. Returns true when the comparison function returns zero. Panics if the provided comparison function is nil.

func EqFn2 

func EqFn2[T any](a, b T, eq CondFunc[T]) bool

EqFn2 returns true if a equals b using a custom equality condition. Returns the direct result of the equality condition function. Panics if the provided equality function is nil.

func Gt 

func Gt[T core.Ordered](a, b T) bool

Gt returns true if a is greater than b for ordered types. Uses the standard Go greater-than operator.

func GtEq 

func GtEq[T core.Ordered](a, b T) bool

GtEq returns true if a is greater than or equal to b for ordered types. Uses the standard Go greater-than-or-equal operator.

func GtEqFn 

func GtEqFn[T any](a, b T, cmp CompFunc[T]) bool

GtEqFn returns true if a is greater than or equal to b using a comparison. Returns true when comparison result is greater than or equal to zero. Panics if the provided comparison function is nil.

func GtEqFn2 

func GtEqFn2[T any](a, b T, less CondFunc[T]) bool

GtEqFn2 returns true if a is greater than or equal to b using a condition. Returns true when a is not less than b using the provided function. Panics if the provided less-than condition function is nil.

func GtFn 

func GtFn[T any](a, b T, cmp CompFunc[T]) bool

GtFn returns true if a is greater than b using a custom comparison function. Returns true when the comparison function returns a positive value. Panics if the provided comparison function is nil.

func Lt 

func Lt[T core.Ordered](a, b T) bool

Lt returns true if a is less than b for ordered types. Uses the standard Go less-than operator.

func LtEq 

func LtEq[T core.Ordered](a, b T) bool

LtEq returns true if a is less than or equal to b for ordered types. Uses the standard Go less-than-or-equal operator.

func LtEqFn 

func LtEqFn[T any](a, b T, cmp CompFunc[T]) bool

LtEqFn returns true if a is less than or equal to b using a comparison function. Returns true when comparison result is less than or equal to zero. Panics if the provided comparison function is nil.

func LtEqFn2 

func LtEqFn2[T any](a, b T, less CondFunc[T]) bool

LtEqFn2 returns true if a is less than or equal to b using a condition. Returns true when b is not less than a using the provided function. Panics if the provided less-than condition function is nil.

func LtFn 

func LtFn[T any](a, b T, cmp CompFunc[T]) bool

LtFn returns true if a is less than b using a custom comparison function. Returns true when the comparison function returns a negative value. Panics if the provided comparison function is nil.

func LtFn2 

func LtFn2[T any](a, b T, less CondFunc[T]) bool

LtFn2 returns true if a is less than b using a less-than condition. Returns the direct result of the less-than condition function. Panics if the provided less-than condition function is nil.

func M 

func M[T any](m Matcher[T]) func(T) bool

M converts a Matcher to a simple function that can be used for matching. If the Matcher is nil, it returns a function that always returns true, allowing seamless usage of Matcher types as boolean functions.

func NotEq 

func NotEq[T comparable](a, b T) bool

NotEq returns true if a does not equal b for comparable types. Uses the standard Go inequality operator.

func NotEqFn 

func NotEqFn[T any](a, b T, cmp CompFunc[T]) bool

NotEqFn returns true if a does not equal b using a custom comparison function. Returns true when the comparison function does not return zero. Panics if the provided comparison function is nil.

func NotEqFn2 

func NotEqFn2[T any](a, b T, eq CondFunc[T]) bool

NotEqFn2 returns true if a does not equal b using an equality condition. Returns the negation of the equality condition function result. Panics if the provided equality function is nil.

Types

type CompFunc 

type CompFunc[T any] func(a, b T) int

CompFunc is a generic comparison function for type T that returns an integer. The return value follows the standard comparison convention: - Negative value if a < b - Zero if a == b - Positive value if a > b

func AsCmp added in v0.2.0 

func AsCmp[T any](less CondFunc[T]) CompFunc[T]

AsCmp converts a less-than condition function into a CompFunc. Panics if the provided condition function is nil.

func Reverse 

func Reverse[T any](cmp CompFunc[T]) CompFunc[T]

Reverse returns a new CompFunc that inverts the result of the given CompFunc. It negates the original comparison, effectively reversing the order. Panics if the provided comparison function is nil.

type CondFunc 

type CondFunc[T any] func(a, b T) bool

CondFunc is a generic condition function for type T that returns a boolean. The return value indicates whether the condition is true or false for the given pair of values.

func AsEqual 

func AsEqual[T any](cmp CompFunc[T]) CondFunc[T]

AsEqual converts a CompFunc into an equality condition function. Returns a function that evaluates to true if the first argument equals the second. Panics if the provided comparison function is nil.

func AsLess 

func AsLess[T any](cmp CompFunc[T]) CondFunc[T]

AsLess converts a CompFunc into a less-than condition function. Returns a function that evaluates to true if the first argument is less than the second. Panics if the provided comparison function is nil.

type MatchFunc 

type MatchFunc[T any] func(T) bool

MatchFunc is a function type that implements the Matcher interface, allowing simple functions to be used as matchers.

func (MatchFunc[T]) And 

func (fn MatchFunc[T]) And(others ...Matcher[T]) Matcher[T]

And combines this matcher function with others using logical AND.

func (MatchFunc[T]) Match 

func (fn MatchFunc[T]) Match(value T) bool

Match calls the matcher function with the provided value. If the function is nil, it returns true (matches everything). This default behaviour makes nil MatchFunc act as a logical identity element, simplifying composition when conditions are optional.

func (MatchFunc[T]) Not 

func (fn MatchFunc[T]) Not() Matcher[T]

Not negates the result of this matcher function, returning a new Matcher that produces the opposite of the original match result.

func (MatchFunc[T]) Or 

func (fn MatchFunc[T]) Or(others ...Matcher[T]) Matcher[T]

Or combines this matcher function with others using logical OR.

type Matcher 

type Matcher[T any] interface {
	// And combines this query with others using logical AND.
	// All conditions must match for the combined query to match.
	// Nil matchers in the provided list are ignored during matching.
	And(...Matcher[T]) Matcher[T]

	// Or combines this query with others using logical OR.
	// At least one condition must match for the combined query to match.
	// Nil matchers in the provided list are ignored during matching.
	Or(...Matcher[T]) Matcher[T]

	// Not negates this matcher's result.
	Not() Matcher[T]

	// Match tests if the given value satisfies this query's conditions.
	Match(T) bool
}

Matcher is a generic interface for filtering and combining predicates of type T. It enables logical AND and OR operations between conditions, and matching against a value.

Matchers are composable, allowing complex matching logic to be built from simpler components. The zero value of any Matcher should either be safe to use or well-documented if it has special behaviour.

func AsMatcher 

func AsMatcher[T any](fn MatchFunc[T]) Matcher[T]

AsMatcher converts a MatchFunc to a Matcher. Returns nil if the provided function is nil.

func Compose 

func Compose[T any, V any](fn func(T) (V, bool), match Matcher[V]) Matcher[T]

Compose creates a new Matcher by applying an accessor function to transform input values before matching against an existing matcher. It enables composition of matchers across different types, allowing you to build complex matching logic by combining simple matchers.

The accessor function (fn) extracts or transforms a value of type T into a value of type V and indicates whether the extraction was successful. The returned matcher evaluates to false if the accessor function returns ok=false.

Common uses include: - Extracting and matching on struct fields - Transforming values before matching - Creating conditional matching chains

Example: 

type Person struct {
    Name string
    Age  int
}

// Create a matcher that checks if a person is an adult
isAdult := Compose(
    func(p Person) (int, bool) { return p.Age, true },
    GtEq(18),
)

Panics if the accessor function or the base matcher is nil.

func MatchAll 

func MatchAll[T any](queries ...Matcher[T]) Matcher[T]

MatchAll returns a query that matches if all of the provided queries match. If no queries are provided, the result will match everything (return true). Nil queries in the provided list are ignored during matching.

func MatchAny 

func MatchAny[T any](queries ...Matcher[T]) Matcher[T]

MatchAny returns a query that matches if any of the provided queries match. If no queries are provided, the result will match nothing (return false). Nil queries in the provided list are ignored during matching.

func MatchEq 

func MatchEq[T comparable](v T) Matcher[T]

MatchEq creates a Matcher that checks for equality with the given value.

Returns a function that yields true if the input equals the specified value. Useful for creating filters or validators that need to match exact values.

Example: 

isApple := MatchEq("apple")
isApple("apple")  // returns true
isApple("banana") // returns false

func MatchEqFn 

func MatchEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]

MatchEqFn creates a Matcher using a custom comparison function. Returns a function that yields true if the input equals the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchEqFn2 

func MatchEqFn2[T any](v T, eq CondFunc[T]) Matcher[T]

MatchEqFn2 creates a Matcher using a custom equality function. Returns a function that yields true if the input equals the specified value according to the provided equality function. Panics if the equality function is nil.

func MatchGt 

func MatchGt[T core.Ordered](v T) Matcher[T]

MatchGt creates a Matcher that checks if a value is strictly greater than the given value. Returns a function that yields true if the input is greater than the specified value.

func MatchGtEq 

func MatchGtEq[T core.Ordered](v T) Matcher[T]

MatchGtEq creates a Matcher that checks if a value is greater than or equal to the given value. Returns a function that yields true if the input is greater than or equal to the specified value.

func MatchGtEqFn 

func MatchGtEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]

MatchGtEqFn creates a Matcher using a custom comparison function. Returns a function that yields true if the input is greater than or equal to the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchGtEqFn2 

func MatchGtEqFn2[T any](v T, less CondFunc[T]) Matcher[T]

MatchGtEqFn2 creates a Matcher using a custom condition function. Returns a function that yields true if the input is greater than or equal to the specified value according to the provided condition function. Panics if the condition function is nil.

func MatchGtFn 

func MatchGtFn[T any](v T, cmp CompFunc[T]) Matcher[T]

MatchGtFn creates a Matcher using a custom comparison function. Returns a function that yields true if the input is greater than the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchLt 

func MatchLt[T core.Ordered](v T) Matcher[T]

MatchLt creates a Matcher that checks if a value is strictly less than the given value. Returns a function that yields true if the input is less than the specified value.

func MatchLtEq 

func MatchLtEq[T core.Ordered](v T) Matcher[T]

MatchLtEq creates a Matcher that checks if a value is less than or equal to the given value. Returns a function that yields true if the input is less than or equal to the specified value.

func MatchLtEqFn 

func MatchLtEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]

MatchLtEqFn creates a Matcher using a custom comparison function. Returns a function that yields true if the input is less than or equal to the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchLtEqFn2 

func MatchLtEqFn2[T any](v T, less CondFunc[T]) Matcher[T]

MatchLtEqFn2 creates a Matcher using a custom condition function. Returns a function that yields true if the input is less than or equal to the specified value according to the provided condition function. Panics if the condition function is nil.

func MatchLtFn 

func MatchLtFn[T any](v T, cmp CompFunc[T]) Matcher[T]

MatchLtFn creates a Matcher using a custom comparison function. Returns a function that yields true if the input is less than the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchLtFn2 

func MatchLtFn2[T any](v T, less CondFunc[T]) Matcher[T]

MatchLtFn2 creates a Matcher using a custom condition function. Returns a function that yields true if the input is less than the specified value according to the provided condition function. Panics if the condition function is nil.

func MatchNotEq 

func MatchNotEq[T comparable](v T) Matcher[T]

MatchNotEq creates a Matcher that checks for inequality with a given value. Returns a function that yields true if the input is not equal to the specified value.

func MatchNotEqFn 

func MatchNotEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]

MatchNotEqFn creates a Matcher using a custom comparison function. Returns a function that yields true if the input is not equal to the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchNotEqFn2 

func MatchNotEqFn2[T any](v T, eq CondFunc[T]) Matcher[T]

MatchNotEqFn2 creates a Matcher using a custom equality function. Returns a function that yields true if the input is not equal to the specified value according to the provided equality function. Panics if the equality function is nil.

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.