(std eq)

Reference

Overview

Equality (Eq), ordering (Ord), and sorting, minimum, and maximum utilities.

(= (list 1 2 3) (list 1 2 3))      ; #t
(compare "apple" "banana")         ; a negative int
(less? 2 3)                        ; #t
(list-sort (list 3 1 2))           ; (1 2 3)
(list-max (list 3 1 2))            ; (Some 3)

The prelude re-exports all identifiers from this module; importing (std prelude) makes this module available automatically.

Eq. The trait provides two methods: = and eq-hash. Every type has an Eq instance. Types without custom instances use the default implementation delegating to .NET Equals and GetHashCode. Primitive types (int, bool, string, char, Keyword, Symbol, StringCursor) have specialized implementations. For double, Equals is used so that NaN equals NaN. All void values are equal.

Container types (List, Vec, Option, Result, and tuples with 2 to 4 elements) compare elements structurally using each element’s =, and compute hashes using eq-hash. List and vector equality checks run iteratively to avoid stack overflows on large collections.

Ord. Defines total ordering via compare. Derived comparison functions and sorting utilities rely solely on compare. Numeric types, bool, and char delegate to .NET CompareTo (including decimal, bigint, int128, uint128, and System.SByte). String comparisons are ordinal (based on Unicode code points) rather than culture-sensitive, ensuring identical cross-platform ordering matching OrderedMap. Tuples with 2 to 4 elements whose elements are ordered are ordered lexicographically: by the first element, then by the second when the first are equal, and so on. (std clr-ord) provides Ord for additional .NET types like Guid and Version.

Custom implementations. Implementations must preserve key invariants: equal values under = must produce identical eq-hash values, and compare must return 0 if and only if values are equal under =.

(impl (Ord Card)
  (defun (compare a b) (compare (card-rank a) (card-rank b))))

See also: =, eq-hash, Ord, compare, list-sort

Reference

Types

Functions

Types

Eq

trait ↑ Types

Trait for structural equality and hashing.

Every type provides an Eq instance. The default instance delegates to .NET Equals and GetHashCode. Custom instances must ensure that equal values yield identical hash codes.

See also: =, eq-hash

Ord

trait ↑ Types

Trait for a total order.

%a
The type to order.
(impl (Ord Card)
  (defun (compare a b) (compare (card-rank a) (card-rank b))))

(list-sort hand)   ; sorted by rank

Requires implementing compare. All relational operators and sorting functions in this module derive from compare. compare must return 0 if and only if two values are equal under =.

See also: compare, less?, list-sort

Functions

=

function ↑ Functions

(: = (-> %a %a bool))

Returns #t if two values are equal, otherwise #f.

a
The first value.
b
The second value.
returns
#t when a and b are equal.
(= "abc" "abc")               ; #t
(= (Some 1) (Some 2))         ; #f

Structural equality method of Eq. Containers compare their items with each item’s =. On double, NaN equals NaN.

See also: eq-hash, compare

eq-hash

function ↑ Functions

(: eq-hash (-> %a int))

Computes a hash code consistent with =.

a
The value to hash.
returns
An int hash code. Equal values produce identical hash codes.

Hashing method of Eq, used by hash sets and hash maps. Container hash codes combine the hashes of their elements in sequence.

See also: =

compare

function ↑ Functions

(: compare (-> %a %a int))

Compares two values for order.

a
The first value.
b
The second value.
returns
A negative int when a < b, 0 when a = b, and a positive int when a > b.

Primary method of Ord. Only the sign of the result is significant. String comparisons are ordinal (based on Unicode code points) and independent of system locale.

See also: less?, greater?, least

less?

function ↑ Functions

(: less? (-> %a %a bool))
(less? a b)

Tests if a is strictly less than b.

a
The first value.
b
The second value.
returns
#t when (compare a b) is negative.

See also: at-most?, greater?, compare

greater?

function ↑ Functions

(: greater? (-> %a %a bool))
(greater? a b)

Tests if a is strictly greater than b.

a
The first value.
b
The second value.
returns
#t when (compare a b) is positive.

See also: at-least?, less?, compare

at-most?

function ↑ Functions

(: at-most? (-> %a %a bool))
(at-most? a b)

Tests if a is less than or equal to b.

a
The first value.
b
The second value.
returns
#t when (compare a b) is not positive.

See also: less?, at-least?, compare

at-least?

function ↑ Functions

(: at-least? (-> %a %a bool))
(at-least? a b)

Tests if a is greater than or equal to b.

a
The first value.
b
The second value.
returns
#t when (compare a b) is not negative.

See also: greater?, at-most?, compare

least

function ↑ Functions

(: least (-> %a %a %a))
(least a b)

Returns the smaller of two values.

a
The first value.
b
The second value.
returns
a when a is at most b, else b. When they are equal, returns a.

See also: greatest, list-min

greatest

function ↑ Functions

(: greatest (-> %a %a %a))
(greatest a b)

Returns the larger of two values.

a
The first value.
b
The second value.
returns
a when a is at least b, else b. When they are equal, returns a.

See also: least, list-max

list-sort

function ↑ Functions

(: list-sort (-> (List %a) (List %a)))
(list-sort xs)

Returns a sorted copy of a list using compare. Stable.

xs
The list to sort.
returns
A list of the same items, in ascending order. Preserves the relative order of equal items.
(list-sort (list 3 1 2))   ; (1 2 3)

Performs a stable merge sort in O(n log n) time. Merges iterative runs using temporary array buffers and constructs the resulting list in a single pass to avoid stack overflows. Lists with fewer than two items return unmodified.

See also: compare, list-min, list-max

vec-sort

function ↑ Functions

(: vec-sort (-> (Vec %a) (Vec %a)))
(vec-sort v)

Returns a sorted copy of a vec using compare. Stable.

v
The vec to sort.
returns
A vec of the same items, in ascending order. Equal items keep their order.
(vec-sort [3 1 2])                           ; [1 2 3]
(vec-sort [(Tuple 2 "b") (Tuple 1 "z")])     ; [(1, z) (2, b)]

The merge sort of list-sort, over an array: O(n log n), and O(n) extra space. A vec of fewer than two items is returned as it is.

See also: vec-sort-by, list-sort, compare

vec-sort-by

function ↑ Functions

(: vec-sort-by (-> (-> %a %a int) (Vec %a) (Vec %a)))
(vec-sort-by cmp v)

Returns a copy of a vec sorted by a comparison function. Stable.

cmp
The comparison: negative when its first argument comes first, zero when the two tie, positive otherwise.
v
The vec to sort.
returns
A vec of the same items, in the order cmp gives. Items that tie keep their order.
(vec-sort-by (fun (a b) (compare b a)) [1 3 2])               ; [3 2 1]
(vec-sort-by (fun (a b) (compare (string-length a) (string-length b)))
             ["ccc" "a" "bb"])                                 ; ["a" "bb" "ccc"]

A comparison that is not a total order gives some order of the items, and no error.

See also: vec-sort, compare

list-min

function ↑ Functions

(: list-min (-> (List %a) (Option %a)))
(list-min xs)

Finds the minimum item in a list, or None if empty.

xs
The list.
returns
(Some item), or None when xs is empty. When multiple items tie for minimum, returns the last occurrence.

See also: list-max, least, list-sort

list-max

function ↑ Functions

(: list-max (-> (List %a) (Option %a)))
(list-max xs)

Finds the maximum item in a list, or None if empty.

xs
The list.
returns
(Some item), or None when xs is empty. When multiple items tie for maximum, returns the last occurrence.

See also: list-min, greatest, list-sort