Documentation
¶
Overview ¶
Package cmp provides generic utility functions, including comparators for ordering values.
Comparators are designed for use in data structures like trees or sorting algorithms.
Index ¶
- Constants
- func Compare[T Ordered](x, y T) int
- func Float64Comparator(x, y, epsilon float64) int
- func Float64ReverseComparator(x, y, epsilon float64) int
- func Float64SimpleComparator(x, y float64) int
- func Float64SimpleReverseComparator(x, y float64) int
- func IsNaN[T Ordered](x T) bool
- func Less[T Ordered](x, y T) bool
- func Or[T comparable](vals ...T) T
- func TimeComparator(a, b time.Time) int
- type Comparator
- type Ordered
Constants ¶
const Epsilon = 1e-15
Epsilon is the default tolerance for floating-point comparisons.
Used in comparators to handle precision issues. Value is 1e-15.
Variables ¶
This section is empty.
Functions ¶
func Compare ¶ added in v0.6.1
Compare returns
-1 if x is less than y, 0 if x equals y, +1 if x is greater than y.
For floating-point types, a NaN is considered less than any non-NaN, a NaN is considered equal to a NaN, and -0.0 is equal to 0.0.
func Float64Comparator ¶
Float64Comparator compares two float64 values directly with an epsilon tolerance.
Accounts for floating-point precision by considering values equal if their difference is within epsilon. Handles special cases like NaN and ±0 consistently with cmp.Compare. Returns:
- -1 if x < y
- 0 if x ≈ y (within epsilon)
- +1 if x > y
Special cases:
- NaN < any non-NaN value
- NaN == NaN
- -0.0 == 0.0
Parameters:
- x, y: Values to compare.
- epsilon: Tolerance for equality (e.g., 1e-10). If ≤ 0, defaults to 1e-15.
Time complexity: O(1).
func Float64ReverseComparator ¶
Float64ReverseComparator compares two float64 values with an epsilon tolerance in reverse order.
Similar to Float64Comparator but returns the opposite result for descending order. Handles special cases like NaN and ±0 consistently with cmp.Compare. Returns:
- -1 if x > y
- 0 if x ≈ y (within epsilon)
- +1 if x < y
Special cases:
- NaN > any non-NaN value (reversed from Float64Comparator)
- NaN == NaN
- -0.0 == 0.0
Parameters:
- x, y: Values to compare.
- epsilon: Tolerance for equality (e.g., 1e-10). If ≤ 0, defaults to 1e-15.
Time complexity: O(1).
func Float64SimpleComparator ¶
Float64SimpleComparator is a simplified version of Float64Comparator that implements Comparator[float64].
Uses the default Epsilon value for comparison tolerance.
Returns:
- -1 if x < y
- 0 if x ≈ y (within Epsilon)
- +1 if x > y
Time complexity: O(1).
Note: This is equivalent to calling NewFloat64Comparator(Epsilon) but avoids the closure overhead.
func Float64SimpleReverseComparator ¶
Float64SimpleReverseComparator is a simplified version of Float64ReverseComparator that implements Comparator[float64].
Uses the default Epsilon value for comparison tolerance.
Returns:
- -1 if x > y
- 0 if x ≈ y (within Epsilon)
- +1 if x < y
Time complexity: O(1).
Note: This is equivalent to calling NewFloat64ReverseComparator(Epsilon) but avoids the closure overhead.
func IsNaN ¶ added in v0.2.0
IsNaN reports whether x is a NaN without requiring the math package. This will always return false if T is not floating-point.
func Less ¶ added in v0.2.0
Less reports whether x is less than y. For floating-point types, a NaN is considered less than any non-NaN, and -0.0 is not less than (is equal to) 0.0.
func Or ¶ added in v0.2.0
func Or[T comparable](vals ...T) T
Or returns the first of its arguments that is not equal to the zero value. If no argument is non-zero, it returns the zero value.
func TimeComparator ¶
TimeComparator compares two time.Time values.
Uses time.Time's After and Before methods for precise ordering. Returns:
- 1 if a > b
- 0 if a == b
- -1 if a < b
Time complexity: O(1).
Types ¶
type Comparator ¶
Comparator defines a function for comparing two values of type T.
Returns:
- -1 if x < y
- 0 if x == y
- +1 if x > y
func NewFloat64Comparator ¶ added in v0.2.0
func NewFloat64Comparator(epsilon float64) Comparator[float64]
NewFloat64Comparator creates a Comparator for float64 values with a specified epsilon tolerance.
Creates a closure that remembers the epsilon value and returns a function conforming to the Comparator[float64] type. This allows pre-configuring the epsilon tolerance without passing it in every comparison operation.
Parameters:
- epsilon: Tolerance for equality (e.g., 1e-10). If ≤ 0, defaults to 1e-15.
Returns:
- A Comparator[float64] function that compares with the specified epsilon.
Time complexity: O(1) for creation, O(1) for each comparison.
func NewFloat64ReverseComparator ¶ added in v0.2.0
func NewFloat64ReverseComparator(epsilon float64) Comparator[float64]
NewFloat64ReverseComparator creates a reverse Comparator for float64 values with a specified epsilon tolerance.
Creates a closure that remembers the epsilon value and returns a function conforming to the Comparator[float64] type. This allows pre-configuring the epsilon tolerance for descending order comparisons without passing it in every operation.
Parameters:
- epsilon: Tolerance for equality (e.g., 1e-10). If ≤ 0, defaults to 1e-15.
Returns:
- A Comparator[float64] function that compares with the specified epsilon in reverse order.
Time complexity: O(1) for creation, O(1) for each comparison.
type Ordered ¶ added in v0.2.0
Ordered is a constraint that permits any ordered type: any type that supports the operators < <= >= >. If future releases of Go add new ordered types, this constraint will be modified to include them.
Note that floating-point types may contain NaN ("not-a-number") values. An operator such as == or < will always report false when comparing a NaN value with any other value, NaN or not. See the Compare function for a consistent way to compare NaN values.
Source Files