ord

Overview ¶

Package ord provides the Ord type class for types that support total ordering.

Overview ¶

An Ord represents a total ordering on a type. It extends Eq (equality) with a comparison function that returns -1, 0, or 1 to indicate less than, equal to, or greater than relationships.

The Ord interface:

type Ord[T any] interface {
    Eq[T]                    // Provides Equals(x, y T) bool
    Compare(x, y T) int      // Returns -1, 0, or 1
}

Ord laws:

• Reflexivity: Compare(x, x) = 0
• Antisymmetry: if Compare(x, y) <= 0 and Compare(y, x) <= 0 then x = y
• Transitivity: if Compare(x, y) <= 0 and Compare(y, z) <= 0 then Compare(x, z) <= 0
• Totality: Compare(x, y) <= 0 or Compare(y, x) <= 0

Basic Usage ¶

Creating an Ord for integers:

intOrd := ord.FromStrictCompare[int]()

result := intOrd.Compare(5, 3)   // 1 (5 > 3)
result := intOrd.Compare(3, 5)   // -1 (3 < 5)
result := intOrd.Compare(5, 5)   // 0 (5 == 5)

equal := intOrd.Equals(5, 5)     // true

Creating a custom Ord:

type Person struct {
    Name string
    Age  int
}

// Order by age
personOrd := ord.MakeOrd(
    func(p1, p2 Person) int {
        if p1.Age < p2.Age {
            return -1
        } else if p1.Age > p2.Age {
            return 1
        }
        return 0
    },
    func(p1, p2 Person) bool {
        return p1.Age == p2.Age
    },
)

Creating Ord from compare function only:

stringOrd := ord.FromCompare(func(a, b string) int {
    if a < b {
        return -1
    } else if a > b {
        return 1
    }
    return 0
})
// Equals is automatically derived from Compare

Comparison Functions ¶

Lt - Less than:

intOrd := ord.FromStrictCompare[int]()
isLessThan5 := ord.Lt(intOrd)(5)

result := isLessThan5(3)  // true
result := isLessThan5(5)  // false
result := isLessThan5(7)  // false

Leq - Less than or equal:

isAtMost5 := ord.Leq(intOrd)(5)

result := isAtMost5(3)  // true
result := isAtMost5(5)  // true
result := isAtMost5(7)  // false

Gt - Greater than:

isGreaterThan5 := ord.Gt(intOrd)(5)

result := isGreaterThan5(3)  // false
result := isGreaterThan5(5)  // false
result := isGreaterThan5(7)  // true

Geq - Greater than or equal:

isAtLeast5 := ord.Geq(intOrd)(5)

result := isAtLeast5(3)  // false
result := isAtLeast5(5)  // true
result := isAtLeast5(7)  // true

Between - Check if value is in range [low, high):

intOrd := ord.FromStrictCompare[int]()
isBetween3And7 := ord.Between(intOrd)(3, 7)

result := isBetween3And7(2)  // false
result := isBetween3And7(3)  // true
result := isBetween3And7(5)  // true
result := isBetween3And7(7)  // false
result := isBetween3And7(8)  // false

Min and Max ¶

Min - Get the minimum of two values:

intOrd := ord.FromStrictCompare[int]()
min := ord.Min(intOrd)

result := min(5, 3)  // 3
result := min(3, 5)  // 3
result := min(5, 5)  // 5 (first argument when equal)

Max - Get the maximum of two values:

max := ord.Max(intOrd)

result := max(5, 3)  // 5
result := max(3, 5)  // 5
result := max(5, 5)  // 5 (first argument when equal)

Clamp - Restrict a value to a range:

intOrd := ord.FromStrictCompare[int]()
clamp := ord.Clamp(intOrd)(0, 100)

result := clamp(-10)  // 0 (clamped to minimum)
result := clamp(50)   // 50 (within range)
result := clamp(150)  // 100 (clamped to maximum)

Transforming Ord ¶

Reverse - Invert the ordering:

intOrd := ord.FromStrictCompare[int]()
reversedOrd := ord.Reverse(intOrd)

result := intOrd.Compare(5, 3)         // 1 (5 > 3)
result := reversedOrd.Compare(5, 3)    // -1 (3 > 5 in reversed order)

min := ord.Min(reversedOrd)
result := min(5, 3)  // 5 (max in original order)

Contramap - Transform the input before comparing:

type Person struct {
    Name string
    Age  int
}

intOrd := ord.FromStrictCompare[int]()

// Order persons by age
personOrd := ord.Contramap(func(p Person) int {
    return p.Age
})(intOrd)

p1 := Person{Name: "Alice", Age: 30}
p2 := Person{Name: "Bob", Age: 25}

result := personOrd.Compare(p1, p2)  // 1 (30 > 25)

ToEq - Convert Ord to Eq:

intOrd := ord.FromStrictCompare[int]()
intEq := ord.ToEq(intOrd)

result := intEq.Equals(5, 5)  // true
result := intEq.Equals(5, 3)  // false

Semigroup and Monoid ¶

Semigroup - Combine orderings (try first, then second):

type Person struct {
    LastName  string
    FirstName string
}

stringOrd := ord.FromStrictCompare[string]()

// Order by last name
byLastName := ord.Contramap(func(p Person) string {
    return p.LastName
})(stringOrd)

// Order by first name
byFirstName := ord.Contramap(func(p Person) string {
    return p.FirstName
})(stringOrd)

// Combine: order by last name, then first name
sg := ord.Semigroup[Person]()
personOrd := sg.Concat(byLastName, byFirstName)

p1 := Person{LastName: "Smith", FirstName: "Alice"}
p2 := Person{LastName: "Smith", FirstName: "Bob"}

result := personOrd.Compare(p1, p2)  // -1 (Alice < Bob)

Monoid - Semigroup with identity (always equal):

m := ord.Monoid[int]()

// Empty ordering considers everything equal
emptyOrd := m.Empty()
result := emptyOrd.Compare(5, 3)  // 0 (always equal)

// Concat with empty returns the original
intOrd := ord.FromStrictCompare[int]()
result := m.Concat(intOrd, emptyOrd)  // same as intOrd

MaxSemigroup - Semigroup that returns maximum:

intOrd := ord.FromStrictCompare[int]()
maxSg := ord.MaxSemigroup(intOrd)

result := maxSg.Concat(5, 3)  // 5
result := maxSg.Concat(3, 5)  // 5

MinSemigroup - Semigroup that returns minimum:

minSg := ord.MinSemigroup(intOrd)

result := minSg.Concat(5, 3)  // 3
result := minSg.Concat(3, 5)  // 3

Practical Examples ¶

Sorting with custom order:

import (
    "sort"
    O "github.com/IBM/fp-go/v2/ord"
)

type Person struct {
    Name string
    Age  int
}

people := []Person{
    {Name: "Alice", Age: 30},
    {Name: "Bob", Age: 25},
    {Name: "Charlie", Age: 35},
}

intOrd := O.FromStrictCompare[int]()
personOrd := O.Contramap(func(p Person) int {
    return p.Age
})(intOrd)

sort.Slice(people, func(i, j int) bool {
    return personOrd.Compare(people[i], people[j]) < 0
})
// people is now sorted by age

Finding min/max in a slice:

import (
    A "github.com/IBM/fp-go/v2/array"
    O "github.com/IBM/fp-go/v2/ord"
)

numbers := []int{5, 2, 8, 1, 9, 3}
intOrd := O.FromStrictCompare[int]()

min := O.Min(intOrd)
max := O.Max(intOrd)

// Find minimum
minimum := A.Reduce(numbers, min, numbers[0])  // 1

// Find maximum
maximum := A.Reduce(numbers, max, numbers[0])  // 9

Multi-level sorting:

type Employee struct {
    Department string
    Name       string
    Salary     int
}

stringOrd := O.FromStrictCompare[string]()
intOrd := O.FromStrictCompare[int]()

// Order by department
byDept := O.Contramap(func(e Employee) string {
    return e.Department
})(stringOrd)

// Order by salary (descending)
bySalary := O.Reverse(O.Contramap(func(e Employee) int {
    return e.Salary
})(intOrd))

// Order by name
byName := O.Contramap(func(e Employee) string {
    return e.Name
})(stringOrd)

// Combine: dept, then salary (desc), then name
sg := O.Semigroup[Employee]()
employeeOrd := sg.Concat(sg.Concat(byDept, bySalary), byName)

Filtering with comparisons:

import (
    A "github.com/IBM/fp-go/v2/array"
    O "github.com/IBM/fp-go/v2/ord"
)

numbers := []int{1, 5, 3, 8, 2, 9, 4}
intOrd := O.FromStrictCompare[int]()

// Filter numbers greater than 5
gt5 := O.Gt(intOrd)(5)
result := A.Filter(gt5)(numbers)  // [8, 9]

// Filter numbers between 3 and 7
between3And7 := O.Between(intOrd)(3, 7)
result := A.Filter(between3And7)(numbers)  // [5, 3, 4]

Functions ¶

Core operations:

• MakeOrd[T any](func(T, T) int, func(T, T) bool) Ord[T] - Create Ord from compare and equals
• FromCompare[T any](func(T, T) int) Ord[T] - Create Ord from compare (derives equals)
• FromStrictCompare[A Ordered]() Ord[A] - Create Ord for built-in ordered types
• ToEq[T any](Ord[T]) Eq[T] - Convert Ord to Eq

Transformations:

• Reverse[T any](Ord[T]) Ord[T] - Invert the ordering
• Contramap[A, B any](func(B) A) func(Ord[A]) Ord[B] - Transform input before comparing

Comparisons:

• Lt[A any](Ord[A]) func(A) func(A) bool - Less than
• Leq[A any](Ord[A]) func(A) func(A) bool - Less than or equal
• Gt[A any](Ord[A]) func(A) func(A) bool - Greater than
• Geq[A any](Ord[A]) func(A) func(A) bool - Greater than or equal
• Between[A any](Ord[A]) func(A, A) func(A) bool - Check if in range [low, high)

Min/Max/Clamp:

• Min[A any](Ord[A]) func(A, A) A - Get minimum of two values
• Max[A any](Ord[A]) func(A, A) A - Get maximum of two values
• Clamp[A any](Ord[A]) func(A, A) func(A) A - Clamp value to range

Algebraic structures:

• Semigroup[A any]() Semigroup[Ord[A]] - Combine orderings
• Monoid[A any]() Monoid[Ord[A]] - Semigroup with identity (always equal)
• MaxSemigroup[A any](Ord[A]) Semigroup[A] - Semigroup returning maximum
• MinSemigroup[A any](Ord[A]) Semigroup[A] - Semigroup returning minimum

Related Packages ¶

• eq: Equality type class (parent of Ord)
• constraints: Type constraints for generics
• semigroup: Associative binary operation
• monoid: Semigroup with identity element