@thi.ng/intervals/index.d.ts

Closed/open/semi-open interval data type, queries & operations

import type { Fn, ICompare, IContains, ICopy, IEquiv } from "@thi.ng/api";
export declare enum Classifier {
    DISJOINT_LEFT = 0,
    DISJOINT_RIGHT = 1,
    EQUIV = 2,
    SUBSET = 3,
    SUPERSET = 4,
    OVERLAP_LEFT = 5,
    OVERLAP_RIGHT = 6
}
export declare class Interval implements ICompare<Interval>, IContains<number>, ICopy<Interval>, IEquiv {
    l: number;
    r: number;
    lopen: boolean;
    ropen: boolean;
    constructor(l: number, r: number, lopen?: boolean, ropen?: boolean);
    get size(): number;
    copy(): Interval;
    /**
     * Compares this interval with `i` and returns a comparator value
     * (-1, 0 or 1). Comparison order is: LHS, RHS, openness.
     *
     * @param i -
     */
    compare(i: Readonly<Interval>): number;
    equiv(i: any): boolean;
    /**
     * Returns true if `x` is lies within this interval.
     *
     * @param x -
     */
    contains(x: number): boolean;
    toString(): string;
    toJSON(): string;
}
export declare function interval(spec: string): Interval;
export declare function interval(l: number, r: number, lopen?: boolean, ropen?: boolean): Interval;
/**
 * Parses given ISO 80000-2 interval notation into a new `Interval`
 * instance. In addition to the comma separator, `..` can be used
 * alternatively. The following symbols (with optional sign) can be
 * used for infinity (case insensitive):
 *
 * - inf
 * - infinity
 * - ∞ (\u221e)
 *
 * An empty LHS defaults to `-Infinity`. The RHS defaults to
 * `+Infinity`.
 *
 * Openness / closedness symbols:
 *
 * - LHS: open: `]` / `(`, closed: `[`
 * - RHS: open: `[` / `)`, closed: `]`
 *
 * ```js
 * import { parse } from "@thi.ng/interval";
 *
 * // semi-open interval between -∞ and +1
 * parse("[,1)")
 *
 * // closed interval between -1 and +1
 * parse("[-1 .. 1]")
 * ```
 *
 * @param src -
 */
export declare const parse: (src: string) => Interval;
/**
 * Returns new infinite interval `[-∞,∞]`
 */
export declare const infinity: () => Interval;
/**
 * Returns new interval of `[min,∞]` or `(min,∞]` depending on if `open` is true
 * (default: false).
 *
 * @param min -
 * @param open -
 */
export declare const withMin: (min: number, open?: boolean) => Interval;
/**
 * Returns new interval of `[∞,max]` or `[∞,max)` depending on if `open` is true
 * (default: false).
 *
 * @param max -
 * @param open -
 */
export declare const withMax: (max: number, open?: boolean) => Interval;
/**
 * Returns an open interval `(min,max)`
 *
 * @param min -
 * @param max -
 */
export declare const open: (min: number, max: number) => Interval;
/**
 * Returns a semi-open interval `(min,max]`, open on the LHS.
 *
 * @param min -
 * @param max -
 */
export declare const openClosed: (min: number, max: number) => Interval;
/**
 * Returns a semi-open interval `[min,max)`, open on the RHS.
 *
 * @param min -
 * @param max -
 */
export declare const closedOpen: (min: number, max: number) => Interval;
/**
 * Returns a closed interval `(min,max)`.
 *
 * @param min -
 * @param max -
 */
export declare const closed: (min: number, max: number) => Interval;
/**
 * Returns iterator of values in given interval at given `step` size. If the
 * interval is open on either side, the first and/or last sample will be
 * omitted.
 *
 * @param i -
 * @param step -
 */
export declare const values: (i: Readonly<Interval>, step: number) => Generator<number, void, unknown>;
/**
 * Returns an iterator yielding up to `n` uniformly spaced samples in given
 * interval. If the interval is open on either side, the first and/or last
 * sample will be omitted.
 *
 * @example
 * ```js
 * import { samples, closed } from "@thi.ng/intervals";
 *
 * [...samples(closed(10, 12), 5)]
 * // [10, 10.5, 11, 11.5, 12]
 *
 * [...samples(open(10, 12), 5)]
 * // [10.5, 11, 11.5]
 * ```
 *
 * @param i -
 * @param n -
 */
export declare function samples(i: Readonly<Interval>, n: number): Generator<number, void, unknown>;
/**
 * Returns true, if interval has zero range, i.e. if LHS >= RHS.
 *
 * @param i -
 */
export declare const isEmpty: (i: Readonly<Interval>) => boolean;
/**
 * Returns true iff interval `i` RHS < `x`, taking into account openness. If `x`
 * is an interval, then checks `i` RHS is less than LHS of `x` (again with
 * openness).
 *
 * @param i -
 * @param x -
 */
export declare const isBefore: (i: Readonly<Interval>, x: number | Readonly<Interval>) => boolean;
/**
 * Returns true iff interval `i` LHS > `x`, taking into account openness. If `x`
 * is an interval, then checks `i` LHS is greater than RHS of `x` (again with
 * openness).
 *
 * @param i -
 * @param x -
 */
export declare const isAfter: (i: Readonly<Interval>, x: number | Readonly<Interval>) => boolean;
/**
 * Compares interval `a` with `b` and returns a comparator value (-1, 0 or 1).
 * Comparison order is: LHS, RHS, openness.
 *
 * @param a -
 * @param b -
 */
export declare const compare: (a: Readonly<Interval>, b: Readonly<Interval>) => number;
/**
 * Returns true if `x` is lies within interval `i`.
 *
 * @param i -
 * @param x -
 */
export declare const contains: (i: Readonly<Interval>, x: number) => boolean;
export declare const centroid: (i: Readonly<Interval>) => number;
/**
 * Returns a new version of interval `i` such that `x` is included. If `x` lies
 * outside the current interval, the new one will be extended correspondingly.
 *
 * @param i -
 * @param x -
 */
export declare const include: (i: Readonly<Interval>, x: number) => Interval;
/**
 * Returns the distance between intervals, or zero if they touch or overlap.
 *
 * @param a -
 * @param b -
 */
export declare const distance: (a: Readonly<Interval>, b: Readonly<Interval>) => number;
/**
 * Applies given `fn` to both sides of interval `i` and returns a new
 * {@link Interval} of transformed end points.
 *
 * @param i -
 * @param fn -
 */
export declare const transform: (i: Readonly<Interval>, fn: Fn<number, number>) => Interval;
/**
 * Returns classifier for interval `a` WRT given interval `b`. E.g. if the
 * result is `Classifier.SUPERSET`, then interval `a` fully contains `b`.
 *
 * ```text
 * EQUIV
 * [   a     ]
 * [   b     ]
 *
 * DISJOINT_LEFT
 * [ b ]
 *       [ a ]
 *
 * DISJOINT_RIGHT
 * [ a ]
 *       [ b ]
 *
 * SUPERSET
 * [ a         ]
 *    [ b   ]
 *
 * SUBSET
 * [ b         ]
 *    [ a ]
 *
 * OVERLAP_RIGHT
 * [ a     ]
 *       [ b ]
 *
 * OVERLAP_LEFT
 * [ b     ]
 *       [ a ]
 * ```
 *
 * @param a -
 * @param b -
 */
export declare const classify: (a: Readonly<Interval>, b: Readonly<Interval>) => Classifier;
/**
 * Returns true if interval `a` intersects `b` in any way (incl. subset /
 * superset).
 *
 * @param a -
 * @param b -
 */
export declare const overlaps: (a: Readonly<Interval>, b: Readonly<Interval>) => boolean;
/**
 * Returns the union of the two given intervals, taken their openness into
 * account.
 *
 * @param a -
 * @param b -
 */
export declare const union: (a: Readonly<Interval>, b: Readonly<Interval>) => Readonly<Interval>;
/**
 * Returns the intersection of the two given intervals, taken their openness
 * into account. Returns undefined if `a` and `b` don't overlap.
 *
 * @param a -
 * @param b -
 */
export declare const intersection: (a: Readonly<Interval>, b: Readonly<Interval>) => Interval | undefined;
export declare const prefix: (a: Readonly<Interval>, b: Readonly<Interval>) => Interval | undefined;
export declare const suffix: (a: Readonly<Interval>, b: Readonly<Interval>) => Interval | undefined;
/**
 * Returns the lesser value of either `x` or interval `i`'s RHS value. If the
 * interval is open on the RHS, and `x >= r`, then `r - eps` will be returned.
 *
 * @param i -
 * @param x -
 * @param eps -
 */
export declare const min: (i: Readonly<Interval>, x: number, eps?: number) => number;
/**
 * Returns the greater value of either `x` or interval `i`'s LHS value. If the
 * interval is open on the LHS, and `x <= l`, then `l + eps` will be returned.
 *
 * @param i -
 * @param x -
 * @param eps -
 */
export declare const max: (i: Readonly<Interval>, x: number, eps?: number) => number;
/**
 * Clamps `x` to interval `i`, using {@link min} and {@link max}.
 *
 * @param i -
 * @param x -
 * @param eps -
 */
export declare const clamp: (i: Readonly<Interval>, x: number, eps?: number) => number;
/**
 * Folds `x` back into interval `i`, should it lie outside. `x` MUST originally
 * lie in the `(i.l-i.size .. i.r+i.size)` interval.
 *
 * @remarks
 * Current implementation is recursive and O(N) where N = ceil(max(|x-i.l|,
 * \x-i.r|) / i.size).
 *
 * See {@link min} or {@link max} for handling of optional `eps` arg.
 *
 * @param i
 * @param x
 * @param eps
 */
export declare const fold: (i: Readonly<Interval>, x: number, eps?: number) => number;
//# sourceMappingURL=index.d.ts.map