eq

func Contramap ¶

func Contramap[A, B any](f func(b B) A) func(Eq[A]) Eq[B]

Contramap creates an Eq[B] from an Eq[A] by providing a function that maps B to A. This is a contravariant functor operation that allows you to transform equality predicates by mapping the input type. It's particularly useful for comparing complex types by extracting comparable fields.

The name "contramap" comes from category theory, where it represents a contravariant functor. Unlike regular map (covariant), which transforms the output, contramap transforms the input in the opposite direction.

Type Parameters:

• A: The type that has an existing Eq instance
• B: The type for which we want to create an Eq instance

Parameters:

• f: A function that extracts or converts a value of type B to type A

Returns:

• A function that takes an Eq[A] and returns an Eq[B]

The resulting Eq[B] compares two B values by:

1. Applying f to both values to get A values
2. Using the original Eq[A] to compare those A values

Example - Compare structs by a single field:

type Person struct {
    ID   int
    Name string
    Age  int
}

// Compare persons by ID only
personEqByID := eq.Contramap(func(p Person) int {
    return p.ID
})(eq.FromStrictEquals[int]())

p1 := Person{ID: 1, Name: "Alice", Age: 30}
p2 := Person{ID: 1, Name: "Bob", Age: 25}
assert.True(t, personEqByID.Equals(p1, p2))  // Same ID, different names

Example - Case-insensitive string comparison:

type User struct {
    Username string
    Email    string
}

caseInsensitiveEq := eq.FromEquals(func(a, b string) bool {
    return strings.EqualFold(a, b)
})

userEqByUsername := eq.Contramap(func(u User) string {
    return u.Username
})(caseInsensitiveEq)

u1 := User{Username: "Alice", Email: "alice@example.com"}
u2 := User{Username: "ALICE", Email: "different@example.com"}
assert.True(t, userEqByUsername.Equals(u1, u2))  // Case-insensitive match

Example - Nested field access:

type Address struct {
    City string
}

type Person struct {
    Name    string
    Address Address
}

// Compare persons by city
personEqByCity := eq.Contramap(func(p Person) string {
    return p.Address.City
})(eq.FromStrictEquals[string]())

Contramap Law: Contramap must satisfy: Contramap(f)(Contramap(g)(eq)) = Contramap(g ∘ f)(eq) This means contramapping twice is the same as contramapping with the composed function.

func Equals ¶

func Equals[T any](eq Eq[T]) func(T) func(T) bool

Equals returns a curried equality checking function. This is useful for partial application and functional composition.

Type Parameters:

• T: The type being compared

Parameters:

• eq: The Eq instance to use for comparison

Returns:

• A function that takes a value and returns another function that checks equality with that value

Example:

intEq := eq.FromStrictEquals[int]()
equals42 := eq.Equals(intEq)(42)

assert.True(t, equals42(42))
assert.False(t, equals42(43))

// Use in higher-order functions
numbers := []int{40, 41, 42, 43, 44}
filtered := array.Filter(equals42)(numbers)
// filtered = [42]

// Partial application
equalsFunc := eq.Equals(intEq)
equals10 := equalsFunc(10)
equals20 := equalsFunc(20)

This is particularly useful when working with functional programming patterns like map, filter, and other higher-order functions.

func Monoid ¶

func Monoid[A any]() M.Monoid[Eq[A]]

Monoid returns a Monoid instance for Eq[A]. A Monoid extends Semigroup with an identity element (Empty). For Eq, the identity is an equality predicate that always returns true.

Type Parameters:

• A: The type for which the equality monoid is defined

Returns:

• A Monoid[Eq[A]] with:
• Concat: Combines equality predicates with logical AND (from Semigroup)
• Empty: An equality predicate that always returns true (identity element)

Monoid Laws:

1. Left Identity: Concat(Empty(), x) = x
2. Right Identity: Concat(x, Empty()) = x
3. Associativity: Concat(Concat(x, y), z) = Concat(x, Concat(y, z))

Example - Using the identity element:

monoid := eq.Monoid[int]()
intEq := eq.FromStrictEquals[int]()

// Empty is the identity - combining with it doesn't change behavior
leftIdentity := monoid.Concat(monoid.Empty(), intEq)
rightIdentity := monoid.Concat(intEq, monoid.Empty())

assert.True(t, leftIdentity.Equals(42, 42))
assert.False(t, leftIdentity.Equals(42, 43))
assert.True(t, rightIdentity.Equals(42, 42))
assert.False(t, rightIdentity.Equals(42, 43))

Example - Empty always returns true:

monoid := eq.Monoid[string]()
alwaysTrue := monoid.Empty()

assert.True(t, alwaysTrue.Equals("hello", "world"))
assert.True(t, alwaysTrue.Equals("same", "same"))
assert.True(t, alwaysTrue.Equals("", "anything"))

Example - Building complex equality with fold:

type Person struct {
    FirstName string
    LastName  string
    Age       int
}

firstNameEq := eq.Contramap(func(p Person) string { return p.FirstName })(eq.FromStrictEquals[string]())
lastNameEq := eq.Contramap(func(p Person) string { return p.LastName })(eq.FromStrictEquals[string]())
ageEq := eq.Contramap(func(p Person) int { return p.Age })(eq.FromStrictEquals[int]())

monoid := eq.Monoid[Person]()
// Combine all predicates - all fields must match
personEq := monoid.Concat(monoid.Concat(firstNameEq, lastNameEq), ageEq)

Use cases:

• Providing a neutral element for equality combinations
• Generic algorithms that require a Monoid instance
• Folding multiple equality predicates into one
• Default "accept everything" equality predicate

func Semigroup ¶

func Semigroup[A any]() S.Semigroup[Eq[A]]

Semigroup returns a Semigroup instance for Eq[A]. A Semigroup provides a way to combine two values of the same type. For Eq, the combination uses logical AND - two values are equal only if they are equal according to BOTH equality predicates.

Type Parameters:

• A: The type for which equality predicates are being combined

Returns:

• A Semigroup[Eq[A]] that combines equality predicates with logical AND

The Concat operation satisfies:

• Associativity: Concat(Concat(x, y), z) = Concat(x, Concat(y, z))

Example - Combine multiple equality checks:

type User struct {
    Username string
    Email    string
}

usernameEq := eq.Contramap(func(u User) string {
    return u.Username
})(eq.FromStrictEquals[string]())

emailEq := eq.Contramap(func(u User) string {
    return u.Email
})(eq.FromStrictEquals[string]())

// Users are equal only if BOTH username AND email match
userEq := eq.Semigroup[User]().Concat(usernameEq, emailEq)

u1 := User{Username: "alice", Email: "alice@example.com"}
u2 := User{Username: "alice", Email: "alice@example.com"}
u3 := User{Username: "alice", Email: "different@example.com"}

assert.True(t, userEq.Equals(u1, u2))   // Both match
assert.False(t, userEq.Equals(u1, u3))  // Email differs

Example - Combine multiple field checks:

type Product struct {
    ID    int
    Name  string
    Price float64
}

idEq := eq.Contramap(func(p Product) int { return p.ID })(eq.FromStrictEquals[int]())
nameEq := eq.Contramap(func(p Product) string { return p.Name })(eq.FromStrictEquals[string]())
priceEq := eq.Contramap(func(p Product) float64 { return p.Price })(eq.FromStrictEquals[float64]())

sg := eq.Semigroup[Product]()
// All three fields must match
productEq := sg.Concat(sg.Concat(idEq, nameEq), priceEq)

Use cases:

• Combining multiple field comparisons for struct equality
• Building complex equality predicates from simpler ones
• Ensuring all conditions are met (logical AND of predicates)