Ordering — essence

What compare returns, #Less, #Equal or #Greater, and then for ordering by a second key.

How one value stands against another: below it, equal to it, or above it.

compare answers one of the three Cases. They are written Ordering#Less, Ordering#Equal and Ordering#Greater, and matched as case #Less. A match over them is checked for exhaustiveness like any other Choice.

Taught on: Protocols and Lists.

Declaration

choice Ordering {
	Less,
	Equal,
	Greater,
}

At a glance

Declared: namespace Ordering for Ordering
Conforms to: Equatable
Printable

The cases

is

on Ordering · derived from Equatable

is(_ other: Ordering) -> Boolean

Answers whether both values are equal.

NameTypeDescription

_Orderingthe value to compare with

Returns true when the values are equal.

Example

expect "Ada"::is("Ada")
expect [1, 2]::is([2, 1])::negate()

toString

on Ordering · derived from Printable

toString() -> String

Answers the value as a String.

Returns the String representation of the value.

Example

expect 42::toString()::is("42")
expect [1, 2]::toString()::is("[1, 2]")

cases

on Ordering · derived from Enumerable

static cases() -> NonEmptyList<Ordering>

Answers every value of the Type.

The values stand in the order the Cases are declared in. A Choice has at least one Case, so the answer certainly holds one.

Returns every Case of the Choice, in declaration order.

isNot

on Ordering · provided by Equatable

isNot(_ other: Ordering) -> Boolean

Answers whether the values differ.

NameTypeDescription

_Orderingthe value to compare with

Returns true when the values differ.

Example

expect "Ada"::isNot("Grace")
expect 3::isNot(3)::negate()

Chaining

then

on Ordering

Answers the ordering, or a second one where the first decides nothing.

Chaining the calls is how a sort orders on a second key, and then on a third. Each ordering after the first decides only what the ones before it left equal.

Example

constant people = [
  { last = "Ott", first = "Zoe" },
  { last = "Ali", first = "Bo" },
  { last = "Ott", first = "Al" },
]

constant ranked = people::sort(by (a, b) {
  <- a.last::compare(to b.last)::then(a.first::compare(to b.first))
})

expect ranked::map((person) { <- person.first })::join(with ", ")::is("Bo, Al, Zoe")

then(_ next: Ordering) -> Ordering

The next ordering is computed before the call, whether or not it is reached.

NameTypeDescription

_Orderingthe ordering to answer when this one is Ordering#Equal

Returns the ordering itself, or the given one in its place.

Example

expect Ordering#Less::then(#Greater)::is(#Less)
expect Ordering#Equal::then(#Greater)::is(#Greater)

then(computedBy next: () -> Ordering) -> Ordering

The Function runs only where the first ordering is Ordering#Equal.

NameTypeDescription

computedBy() -> Orderinganswers the ordering to use when this one is Ordering#Equal

Returns the ordering itself, or the one the Function answers.

Example

expect Ordering#Less::then(computedBy () -> Ordering { <- #Greater })::is(#Less)