/**
 * The `Ordering` module provides the standard representation for the result of
 * comparing two values. An `Ordering` is one of three numeric literals: `-1`
 * when the first value is less than the second, `0` when both values compare as
 * equal, and `1` when the first value is greater than the second.
 *
 * **Mental model**
 *
 * - `Ordering` describes the relationship between two compared values, not the
 *   values themselves
 * - Negative means "less than", zero means "equal", and positive means "greater
 *   than"
 * - Unlike JavaScript comparators, this type is normalized to exactly `-1`, `0`,
 *   or `1`
 * - `0` is neutral when combining comparisons; the first non-zero ordering
 *   determines the result
 *
 * **Common tasks**
 *
 * - Interpret a comparison result with {@link match}
 * - Reverse ascending and descending order with {@link reverse}
 * - Combine multiple comparison criteria with {@link Reducer}
 * - Build custom comparison functions for sorting, ordered collections, and
 *   domain-specific ordering rules
 *
 * **Gotchas**
 *
 * - Do not cast arbitrary comparator results such as `a.localeCompare(b)`
 *   directly unless they have been normalized to `-1`, `0`, or `1`
 * - In comparator-style APIs, `-1` means the left value should come before the
 *   right value, while `1` means it should come after
 * - Reversing an `Ordering` swaps `-1` and `1`, but leaves `0` unchanged
 *
 * @since 2.0.0
 */
import type { LazyArg } from "./Function.ts";
import * as Reducer_ from "./Reducer.ts";
/**
 * Represents the result of comparing two values.
 *
 * **When to use**
 *
 * Use to model a normalized comparison result that is exactly less than,
 * equal to, or greater than.
 *
 * **Details**
 *
 * - `-1` indicates the first value is less than the second
 * - `0` indicates the values are equal
 * - `1` indicates the first value is greater than the second
 *
 * **Example** (Defining comparison results)
 *
 * ```ts
 * import type { Ordering } from "effect"
 *
 * // Custom comparison function
 * const compareNumbers = (a: number, b: number): Ordering.Ordering => {
 *   if (a < b) return -1
 *   if (a > b) return 1
 *   return 0
 * }
 *
 * console.log(compareNumbers(5, 10)) // -1 (5 < 10)
 * console.log(compareNumbers(10, 5)) // 1 (10 > 5)
 * console.log(compareNumbers(5, 5)) // 0 (5 == 5)
 *
 * // Using with string comparison
 * const compareStrings = (a: string, b: string): Ordering.Ordering => {
 *   return a.localeCompare(b) as Ordering.Ordering
 * }
 * ```
 *
 * @category models
 * @since 2.0.0
 */
export type Ordering = -1 | 0 | 1;
/**
 * Reverses the ordering of the input Ordering.
 * This is useful for creating descending sort orders from ascending ones.
 *
 * **When to use**
 *
 * Use to flip an ordering result when reversing sort direction or comparison
 * priority.
 *
 * **Example** (Reversing comparison order)
 *
 * ```ts
 * import { Ordering } from "effect"
 *
 * // Basic reversal
 * console.log(Ordering.reverse(1)) // -1 (greater becomes less)
 * console.log(Ordering.reverse(-1)) // 1 (less becomes greater)
 * console.log(Ordering.reverse(0)) // 0 (equal stays equal)
 *
 * // Creating descending sort from ascending comparison
 * const compareNumbers = (a: number, b: number): Ordering.Ordering =>
 *   a < b ? -1 : a > b ? 1 : 0
 *
 * const compareDescending = (a: number, b: number): Ordering.Ordering =>
 *   Ordering.reverse(compareNumbers(a, b))
 *
 * const numbers = [3, 1, 4, 1, 5]
 * numbers.sort(compareNumbers) // [1, 1, 3, 4, 5] (ascending)
 * numbers.sort(compareDescending) // [5, 4, 3, 1, 1] (descending)
 *
 * // Useful for toggling sort direction
 * const createSorter = (ascending: boolean) => (a: number, b: number) => {
 *   const ordering = compareNumbers(a, b)
 *   return ascending ? ordering : Ordering.reverse(ordering)
 * }
 * ```
 *
 * @category transforming
 * @since 2.0.0
 */
export declare const reverse: (o: Ordering) => Ordering;
/**
 * Matches an `Ordering` value and returns the branch selected by that ordering.
 *
 * **When to use**
 *
 * Use to branch on the three possible comparison outcomes in one expression.
 *
 * **Example** (Pattern matching on orderings)
 *
 * ```ts
 * import { Function, Ordering } from "effect"
 * import * as assert from "node:assert"
 *
 * const toMessage = Ordering.match({
 *   onLessThan: Function.constant("less than"),
 *   onEqual: Function.constant("equal"),
 *   onGreaterThan: Function.constant("greater than")
 * })
 *
 * assert.deepStrictEqual(toMessage(-1), "less than")
 * assert.deepStrictEqual(toMessage(0), "equal")
 * assert.deepStrictEqual(toMessage(1), "greater than")
 * ```
 *
 * @category pattern matching
 * @since 2.0.0
 */
export declare const match: {
    /**
     * Matches an `Ordering` value and returns the branch selected by that ordering.
     *
     * **When to use**
     *
     * Use to branch on the three possible comparison outcomes in one expression.
     *
     * **Example** (Pattern matching on orderings)
     *
     * ```ts
     * import { Function, Ordering } from "effect"
     * import * as assert from "node:assert"
     *
     * const toMessage = Ordering.match({
     *   onLessThan: Function.constant("less than"),
     *   onEqual: Function.constant("equal"),
     *   onGreaterThan: Function.constant("greater than")
     * })
     *
     * assert.deepStrictEqual(toMessage(-1), "less than")
     * assert.deepStrictEqual(toMessage(0), "equal")
     * assert.deepStrictEqual(toMessage(1), "greater than")
     * ```
     *
     * @category pattern matching
     * @since 2.0.0
     */
    <A, B, C = B>(options: {
        readonly onLessThan: LazyArg<A>;
        readonly onEqual: LazyArg<B>;
        readonly onGreaterThan: LazyArg<C>;
    }): (self: Ordering) => A | B | C;
    /**
     * Matches an `Ordering` value and returns the branch selected by that ordering.
     *
     * **When to use**
     *
     * Use to branch on the three possible comparison outcomes in one expression.
     *
     * **Example** (Pattern matching on orderings)
     *
     * ```ts
     * import { Function, Ordering } from "effect"
     * import * as assert from "node:assert"
     *
     * const toMessage = Ordering.match({
     *   onLessThan: Function.constant("less than"),
     *   onEqual: Function.constant("equal"),
     *   onGreaterThan: Function.constant("greater than")
     * })
     *
     * assert.deepStrictEqual(toMessage(-1), "less than")
     * assert.deepStrictEqual(toMessage(0), "equal")
     * assert.deepStrictEqual(toMessage(1), "greater than")
     * ```
     *
     * @category pattern matching
     * @since 2.0.0
     */
    <A, B, C = B>(o: Ordering, options: {
        readonly onLessThan: LazyArg<A>;
        readonly onEqual: LazyArg<B>;
        readonly onGreaterThan: LazyArg<C>;
    }): A | B | C;
};
/**
 * Reducer for combining `Ordering`s.
 *
 * **When to use**
 *
 * Use to combine multiple comparison results in priority order, such as
 * checking secondary criteria only when earlier criteria compare as equal.
 *
 * **Details**
 *
 * If any of the `Ordering`s is non-zero, the result is the first non-zero `Ordering`.
 * If all the `Ordering`s are zero, the result is zero.
 *
 * **Gotchas**
 *
 * `combineAll` stops consuming the iterable as soon as it finds a non-zero
 * `Ordering`.
 *
 * @category ordering
 * @since 4.0.0
 */
export declare const Reducer: Reducer_.Reducer<Ordering>;
//# sourceMappingURL=Ordering.d.ts.map