functionalscript/types/range_map/module.f.d.ts

FunctionalScript is a purely functional subset of JavaScript

/**
 * Utility functions and types for managing and merging range maps.
 *
 * @module
 *
 * @example
 *
 * ```js
 * const rmOps = rangeMap({
 *     union: a => b => a | b,
 *     equal: a => b => a === b,
 *     def: 0,
 * })
 *
 * // Create range maps
 * const range1 = rmOps.fromRange([0, 10])(2)
 * const range2 = rmOps.fromRange([5, 15])(5)
 *
 * // Merge range maps
 * const merged = toArray(rmOps.merge(range1)(range2))
 *
 * // Retrieve values from the merged range map
 * //
 * if (rmOps.get(-1)(merged) !== 0) { throw 'error' }
 * //
 * if (rmOps.get(0)(merged) !== 2) { throw 'error' }
 * if (rmOps.get(2)(merged) !== 2) { throw 'error' }
 * // overlapped: 2 | 5 = 7
 * if (rmOps.get(7)(merged) !== 7) { throw 'error' }
 * //
 * if (rmOps.get(12)(merged) !== 5) { throw 'error' }
 * if (rmOps.get(15)(merged) !== 5) { throw 'error' }
 * //
 * if (rmOps.get(16)(merged) !== 0) { throw 'error' }
 * ```
 */
import { type SortedList } from '../sorted_list/module.f.ts';
import type { Reduce, Equal } from '../function/operator/module.f.ts';
import type { Range } from '../range/module.f.ts';
export type Entry<T> = [T, number];
/**
 * A sorted list of entries, where each entry is a tuple `[T, number]` that maps a value of type `T` to an upper boundary
 * of a numeric range.
 */
export type RangeMap<T> = SortedList<Entry<T>>;
export type RangeMapArray<T> = readonly Entry<T>[];
/**
 * Defines the properties and operations required for managing range maps.
 */
export type Properties<T> = {
    /**
     * A function to merge two values of type `T`. This defines how overlapping ranges are combined.
     */
    readonly union: Reduce<T>;
    /**
     * A function to check equality between two values of type `T`.
     */
    readonly equal: Equal<T>;
    /**
     * The default value used when no range matches or for initializing ranges.
     */
    readonly def: T;
};
export type RangeMerge<T> = Reduce<RangeMap<T>>;
export declare const merge: <T>(op: Properties<T>) => RangeMerge<T>;
export declare const get: <T>(def: T) => (value: number) => (rm: RangeMapArray<T>) => T;
export declare const fromRange: <T>(def: T) => (r: Range) => (value: T) => RangeMapArray<T>;
/**
 * Represents a set of operations for managing range maps.
 */
export type RangeMapOp<T> = {
    /**
     * Merges two range maps into a single range map.
     */
    readonly merge: RangeMerge<T>;
    /**
     * Retrieves the value associated with a given numeric range.
     */
    readonly get: (value: number) => (rm: RangeMapArray<T>) => T;
    /**
     * Constructs a range map for a single numeric range and value.
     */
    readonly fromRange: (r: Range) => (value: T) => RangeMapArray<T>;
};
/**
 * Creates a set of operations for managing range maps using the specified properties.
 *
 * @param op - The properties defining union and equality operations and the default value.
 * @returns An object containing operations for merging, retrieving, and constructing range maps.
 */
export declare const rangeMap: <T>(op: Properties<T>) => RangeMapOp<T>;