awoken-bible-reference/dist/types/geometry.d.ts

Bible verse reference parser, generator and manipulator

/**
 * Various utility functions for treating [[BibleRef]]s as geometry, IE:
 * BibleVerse's as points, and BibleRange's as line segments, and then finding intersections/etc
 */
import { BibleRef, BibleVerse, BibleRefLibData } from './BibleRef';
export interface GeometryFunctions {
    getIntersection(a: BibleRef | BibleRef[], b: BibleRef | BibleRef[]): BibleRef[];
    intersects(a: BibleRef | BibleRef[], b: BibleRef | BibleRef[]): boolean;
    contains(a: BibleRef, b: BibleRef): boolean;
    getUnion(a: BibleRef | BibleRef[], b: BibleRef | BibleRef[]): BibleRef[];
    getDifference(a: BibleRef | BibleRef[], b: BibleRef | BibleRef[]): BibleRef[];
    indexOf(a: BibleRef | BibleRef[], b: BibleVerse): number;
    verseAtIndex(a: BibleRef | BibleRef[], idx: number): BibleVerse | undefined;
    createIntersectionSet(a: BibleRef | BibleRef[]): IntersectionSet;
    combineRanges(refs: BibleRef[]): BibleRef[];
}
/**
 *  Represents a 1d line segment (we map [[BibleRange]]'s to vidx ranges to do maths on them)
 *
 * @private
 */
export interface LineSegment {
    min: number;
    max: number;
}
/**
 * Generates the most compressed representation possible of some set of
 * [[BibleVerse]]s/[[BibleRange]]s by combining adjacent or overlapping ranges into
 * larger ones
 *
 * For example, an input list of "Gen 1", "Gen 2", "Gen 3", would produce a
 * single [[BibleRange]] for "Gen 1-3"
 *
 * Order of input ranges in unimportant, since this functional will interally
 * call [[sort]] first
 */
export declare function combineRanges(this: BibleRefLibData, refs: BibleRef[]): BibleRef[];
/**
 * Opaque type containing data for use by `getIntersection` or `intersects`
 */
export declare type IntersectionSet = {
    segments: LineSegment[];
};
/**
 * Precomputes data regarding BibleRef list as used by `getIntersection` and `intersects`
 *
 * This is more performant if you call either of these functions multiple times where one of the two
 * inputs remains constant
 */
export declare function createIntersectionSet(this: BibleRefLibData, x: BibleRef | BibleRef[]): IntersectionSet;
/**
 * Creates a new array of [[BibleRef]]s which represents the intersection between two other sets
 *
 * @param this - Any object with a `versification` field
 * @param x    - First set of [[BibleRef]] instances
 * @param y    - Second set of [[BibleRef]] instances
 *
 * @return Simplified and sorted list of [[BibleRef]]s which appear in both input sets. Will
 * return empty array if there are no verses in common between the inputs
 */
export declare function getIntersection(this: BibleRefLibData, x: BibleRef | BibleRef[] | IntersectionSet, y: BibleRef | BibleRef[] | IntersectionSet): BibleRef[];
/**
 * Determines whether two sets of [[BibleRef]]s have any verses in common
 *
 * This is much faster on large data sets than `getIntersection` when just a boolean result is
 * required
 */
export declare function intersects(this: BibleRefLibData, x: BibleRef | BibleRef[] | IntersectionSet, y: BibleRef | BibleRef[] | IntersectionSet): boolean;
/**
 * Determines whether `outer` fully contains all verses present within `inner`
 */
export declare function contains(this: BibleRefLibData, outer: BibleRef | BibleRef[], inner: BibleRef | BibleRef[]): boolean;
/**
 * Returns the union of two sets of [[BibleRef]]s, IE: the combined and simpified set of verses
 * which are in one or the other or both input sets
 */
export declare function getUnion(this: BibleRefLibData, a: BibleRef | BibleRef[], b: BibleRef | BibleRef[]): BibleRef[];
/**
 * Computes the subtraction of two sets of [[BibleRef]]s, returing a new list of [[BibleRef]]
 * instances containing all verses in set `x` but not in set `y`
 *
 * @param x - The left hand set
 * @param y - The right hand set
 * @return Set operation `x \ y` -> IE: all verses in `x` but not in `y`
 */
export declare function getDifference(this: BibleRefLibData, x: BibleRef | BibleRef[], y: BibleRef | BibleRef[]): BibleRef[];
/**
 * Given a (potentially non-continous) set of [[BibleRef]]'s, computes the index of some
 * [[BibleVerse]] within the set.
 *
 * For example, given the input set "Revelation 1:1; Exodus 1:2-4; Genesis 10:5" the following
 * verses appear at each index:
 * - 0: Revelation 1:1
 * - 1: Exodus 1:2
 * - 2: Exodus 1:3
 * - 3: Exodus 1:4
 * - 4: Genesis 10:5
 *
 * @param array - The array of input verses you wish to search (aka, the haystack)
 * @param verse - The verse whose index you wish to determnine (aka, the needle)
 * @return The zero based index at which `verse` can be found, or -1 if the `verse` does not appear
 * within the input `array`
 *
 * @note If the same verse appears at multiple positions within the input array then only the
 * first index is returned
 *
 * @note The inverse of this function is [[verseAtIndex]]
 */
export declare function indexOf(this: BibleRefLibData, array: BibleRef | BibleRef[], verse: BibleVerse): number;
/**
 * Given a (potentially non-continous) set of [[BibleRef]]'s, finds the [[BibleVerse]] at the
 * specified index. This is the inverse of [[indexOf]]
 *
 * @param array - The set of [[BibleRef]] instances (or singular instance) to extract a verse from
 * @param index - The zero based index of the verse you wish to extract from the input set
 *
 * @return BibleVerse instance, or undefined if `index` is out of bounds
 *
 * @note Semantically, the call `AwokenRef.verseAtIndex(array, n)` is equivalent to
 * `AwokenRef.splitByVerse(array)[n]`, however this version is more efficent for a single call,
 * since it does not have build the full temporary array, but intead internally operates by
 * blocks of verses represented by the [[BibleRef]] instances in the input `array`
 */
export declare function verseAtIndex(this: BibleRefLibData, array: BibleRef | BibleRef[], index: number): BibleVerse | undefined;