Packages
gleam_stdlib
0.58.0
1.0.3
1.0.2
1.0.1
1.0.0
0.71.0
0.70.0
0.69.0
0.68.1
0.68.0
0.67.1
0.67.0
0.65.0
0.64.0
0.63.2
0.63.1
0.63.0
0.62.1
0.62.0
0.61.0
0.60.0
0.59.0
0.58.0
0.57.0
0.56.0
0.55.0
0.54.0
0.53.0
0.52.0
0.51.0
0.50.0
0.49.0
0.48.0
0.47.0
0.46.0
0.45.0
0.44.0
0.43.0
0.42.0
0.41.0
0.40.0
0.39.0
0.38.0
0.37.0
0.36.0
0.35.1
0.35.0
0.34.0
0.33.1
0.33.0
0.32.1
0.32.0
0.31.0
0.30.2
0.30.1
0.30.0
0.29.2
0.29.1
0.29.0
0.28.2
0.28.1
0.28.0
0.27.0
0.26.1
0.26.0
0.25.0
0.24.0
0.23.0
0.22.3
0.22.2
0.22.1
0.22.0
0.21.0
0.20.0
0.19.3
0.19.2
0.19.1
0.19.0
0.18.1
0.18.0
0.18.0-rc1
0.17.1
0.17.0
0.16.0
0.15.0
0.14.0
0.13.0
0.12.0
0.11.0
0.10.1
0.10.0
0.9.0
0.8.0
0.7.0
0.6.0
0.5.0
0.4.0
0.4.0-rc1
0.3.1
0.3.0
0.2.0
retired
A standard library for the Gleam programming language
Current section
Files
Jump to
Current section
Files
src/gleam/order.gleam
/// Represents the result of a single comparison to determine the precise
/// ordering of two values.
///
pub type Order {
/// Less-than
Lt
/// Equal
Eq
/// Greater than
Gt
}
/// Inverts an order, so less-than becomes greater-than and greater-than
/// becomes less-than.
///
/// ## Examples
///
/// ```gleam
/// negate(Lt)
/// // -> Gt
/// ```
///
/// ```gleam
/// negate(Eq)
/// // -> Eq
/// ```
///
/// ```gleam
/// negate(Gt)
/// // -> Lt
/// ```
///
pub fn negate(order: Order) -> Order {
case order {
Lt -> Gt
Eq -> Eq
Gt -> Lt
}
}
/// Produces a numeric representation of the order.
///
/// ## Examples
///
/// ```gleam
/// to_int(Lt)
/// // -> -1
/// ```
///
/// ```gleam
/// to_int(Eq)
/// // -> 0
/// ```
///
/// ```gleam
/// to_int(Gt)
/// // -> 1
/// ```
///
pub fn to_int(order: Order) -> Int {
case order {
Lt -> -1
Eq -> 0
Gt -> 1
}
}
/// Compares two `Order` values to one another, producing a new `Order`.
///
/// ## Examples
///
/// ```gleam
/// compare(Eq, with: Lt)
/// // -> Gt
/// ```
///
pub fn compare(a: Order, with b: Order) -> Order {
case a, b {
x, y if x == y -> Eq
Lt, _ | Eq, Gt -> Lt
_, _ -> Gt
}
}
/// Inverts an ordering function, so less-than becomes greater-than and greater-than
/// becomes less-than.
///
/// ## Examples
///
/// ```gleam
/// import gleam/int
/// import gleam/list
///
/// list.sort([1, 5, 4], by: reverse(int.compare))
/// // -> [5, 4, 1]
/// ```
///
pub fn reverse(orderer: fn(a, a) -> Order) -> fn(a, a) -> Order {
fn(a, b) { orderer(b, a) }
}
/// Return a fallback `Order` in case the first argument is `Eq`.
///
/// ## Examples
///
/// ```gleam
/// import gleam/int
///
/// break_tie(in: int.compare(1, 1), with: Lt)
/// // -> Lt
/// ```
///
/// ```gleam
/// import gleam/int
///
/// break_tie(in: int.compare(1, 0), with: Eq)
/// // -> Gt
/// ```
///
pub fn break_tie(in order: Order, with other: Order) -> Order {
case order {
Lt | Gt -> order
Eq -> other
}
}
/// Invokes a fallback function returning an `Order` in case the first argument
/// is `Eq`.
///
/// This can be useful when the fallback comparison might be expensive and it
/// needs to be delayed until strictly necessary.
///
/// ## Examples
///
/// ```gleam
/// import gleam/int
///
/// lazy_break_tie(in: int.compare(1, 1), with: fn() { Lt })
/// // -> Lt
/// ```
///
/// ```gleam
/// import gleam/int
///
/// lazy_break_tie(in: int.compare(1, 0), with: fn() { Eq })
/// // -> Gt
/// ```
///
pub fn lazy_break_tie(in order: Order, with comparison: fn() -> Order) -> Order {
case order {
Lt | Gt -> order
Eq -> comparison()
}
}