silk/order

Compile-time ordering witnesses and a three-way result derived from strict comparison.

When to use

Add an Order bound when a generic algorithm needs <, as sorting and binary search do. Use compare when all three outcomes matter, or less and equal for predicates.

Details

An interface witness is selected during specialization; it creates no service requirement or runtime dispatch. Equal means neither operand orders before the other, so equality cannot disagree with the witness's own strict ordering.

Gotchas

A witness must define a strict total order. The module cannot verify this law. If two different values are incomparable, compare and equal report them as equal.

Examples

Classify each comparison result

import silk.order as Order

pub fn main() -> i32 {
  let low = Order.compare<i32>(2, 7)
  let same = Order.compare<i32>(7, 7)
  let high = Order.compare<i32>(9, 7)
  if !Order.isLess(&low) {
    return 1
  }
  if !Order.isEqual(&same) {
    return 2
  }
  if !Order.isGreater(&high) {
    return 3
  }
  return 42
}

Import as Order with import silk.order.

Public declarations: 11.

Less

pub struct Less

The left value orders before the right value.

Equal

pub struct Equal

Neither value orders before the other.

Greater

pub struct Greater

The left value orders after the right value.

Ordering

pub struct Ordering

A three-way comparison result that contains exactly one of Less, Equal, or Greater.

Field value

pub value: silk/order.Equal | silk/order.Greater | silk/order.Less

The comparison result, which a match expression narrows to one outcome type.

Order

pub interface Order

Static strict-ordering contract for primitive comparable values.

When to use

Use this interface when a generic algorithm needs strict ordering through <.

Details

A witness supplies the strict lessThan the operator < spells. Equality is derived from it rather than declared, so a witness cannot disagree with itself about which values are equal.

Gotchas

An implementation must define a strict total order. If two different values are incomparable, compare and equal treat them as equal.

Operation lessThan

operator < fn lessThan(left: &Self, right: &Self) -> bool

Reports whether left orders strictly before right. An implementation must define a strict total order so different values are not incomparable.

Implementation Order for u8

impl Order for u8

Operation lessThan

lessThan = Intrinsic.u8LessThan

Implementation Order for u16

impl Order for u16

Operation lessThan

lessThan = Intrinsic.u16LessThan

Implementation Order for u32

impl Order for u32

Operation lessThan

lessThan = Intrinsic.u32LessThan

Implementation Order for u64

impl Order for u64

Operation lessThan

lessThan = Intrinsic.u64LessThan

Implementation Order for usize

impl Order for usize

Operation lessThan

lessThan = Intrinsic.usizeLessThan

Implementation Order for i8

impl Order for i8

Operation lessThan

lessThan = Intrinsic.i8LessThan

Implementation Order for i16

impl Order for i16

Operation lessThan

lessThan = Intrinsic.i16LessThan

Implementation Order for i32

impl Order for i32

Operation lessThan

lessThan = Intrinsic.i32LessThan

Implementation Order for i64

impl Order for i64

Operation lessThan

lessThan = Intrinsic.i64LessThan

Implementation Order for isize

impl Order for isize

Operation lessThan

lessThan = Intrinsic.isizeLessThan

compare

pub fn compare<T>(left: T, right: T) -> Ordering

Compares two values three ways using the concrete comparison selected during specialization.

When to use

Use this function when the caller needs to distinguish less, equal, and greater outcomes.

Details

Calls the selected strict comparison with left, right. If that result is false, it calls the comparison with right, left. The function then consumes both owned arguments.

Gotchas

If neither comparison is true, this function returns Equal. The witness must not leave two different values incomparable.

less

pub fn less<T>(left: T, right: T) -> bool

Reports whether left orders strictly before right under the selected Order witness. The function calls the witness once and then consumes both owned arguments.

equal

pub fn equal<T>(left: T, right: T) -> bool

Reports whether neither value orders before the other under the selected Order witness. The function calls the witness once or twice and then consumes both owned arguments.

Gotchas

If the witness leaves different values incomparable, this function reports them as equal.

isLess

pub fn isLess(ordering: &silk/order.Ordering) -> bool

Reports whether an ordering is Less.

isEqual

pub fn isEqual(ordering: &silk/order.Ordering) -> bool

Reports whether an ordering is Equal.

isGreater

pub fn isGreater(ordering: &silk/order.Ordering) -> bool

Reports whether an ordering is Greater.