fp-search-algorithms

/** * ### HashSet * * Value equality is determined by `isEqual` * * If your values are Javascript [primitives](https://developer.mozilla.org/en-US/docs/Glossary/Primitive), there is no benefit in using a HashSet over the native [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set). * * #### Construction * `HashSet` is a newable class, and has the static `HashSet.from` functional constructor for convenience and accepts the same arguments * * #### Native Set API * The HashSet API fully implements the Set API and can act as a drop-in replacement with a few caveats: * * Non-primitive Set values are equal by reference, a Set may contain two different values that share the same structure. A HashSet will not see those values as being different * * Order of insertion is not retained * * Those methods are: * * `clear`, `delete`, `entries`, `forEach`, `add`, `has`, `keys`, `values`, `[Symbol.Iterator]` * * readonly prop `size` * * #### Set Composition API * * The hashSet API also fully implements the new Composition API methods with one caveat: * * Unlike the Set methods which all except "set-like" objects, HashSet _only_ accepts another HashSet in their arguments * * Those methods are: * * `difference`, `intersection`, `isDisjointFrom`, `isSubsetOf`, `isSupersetOf`, `symmetricDifference`, `union` * * #### Array API * HashSet partially implements the Array API, specifically the reduction methods that can apply. * The callbackfn signatures match their array equivalent but without the `index: number` argument * * Those methods are: * * `map`, `filter`, `find`, `reduce`, `some`, `every` * * Notes: * * `map` and `filter` are immutable, returning a new instance of HashSet * * #### Additional Utility APIs * * `clone` - will return a new instance of a HashSet with the exact same values * * `equals` - determine if another HashSet is equal to `this` by determining they share the same values * * Therefor `hashSet.equals(hashSet.clone())` will always return `true` * * #### Custom Equality and Hashing * Internally, class instances who's prototypes implement `equals: (other: typeof this) => boolean` and `hashCode(self: typeof this) => number` * will be used to determine equality between instances and an instance's hash value respectively. * It is recommended to implement these on any class where equality cannot be determined testing on public properties only * * @category Structures */ export declare class HashSet<T> implements Iterable<T> { private dict; /** * Create a HashSet from a Set. * * Note: If your Set has non-primitive values that do not equal by reference but deep-equal by structure, only a single value will retain in the HashSet. * * @group Constructors */ static from<T>(set: Set<T>): HashSet<T>; /** * Create a HashSet from an Array. * * Note: If your Array has non-primitive values that do not equal by reference but deep-equal by structure, only a single value will retain in the HashSet. * * @group Constructors */ static from<T>(values: readonly T[]): HashSet<T>; /** * Create a HashSet from an Iterable. * * Note: If your Iterable has non-primitive values that do not equal by reference but deep-equal by structure, only a single value will retain in the HashSet. * * @group Constructors */ static from<T>(iterable: Iterable<T>): HashSet<T>; /** * Create an empty HashSet. */ constructor(); /** * Create a HashSet from an Array. * * Note: If your Array has non-primitive values that do not equal by reference but deep-equal by structure, only a single value will retain in the HashSet. */ constructor(values?: readonly T[] | null); /** * Create a HashSet from an Iterable. * * Note: If your Iterable has non-primitive values that do not equal by reference but deep-equal by structure, only a single value will retain in the HashSet. */ constructor(iterable?: Iterable<T> | null); /** * Create an immutable copy of the HashSet * @group Utility */ clone(): HashSet<T>; /** * Check if this HashSet is equal to another * Returns `true` when * * referentially equal * * both HashSets contain exactly the same values * * both are empty * * @group Utility */ equals(other: HashSet<T>): boolean; /** * Used internally by `getHash()` * @group Utility */ private hashCode; /** * @group Entries * @returns the number of (unique) elements in Set. */ get size(): number; /** * Adds a new element with a specified value to the HashSet. * @group Entries */ add(val: T): this; /** * * Empties the HashSet, clearing out all values. * @group Entries */ clear(): void; /** * Removes a specified value from the HashSet. * @group Entries * @returns Returns true if an element in the HashSet existed and has been removed, or false if the element does not exist. */ delete(val: T): boolean; /** * @group Entries * @returns a boolean indicating whether an element with the specified value exists in the HashSet or not. */ has(val: T): boolean; /** * Executes a provided function once per each value in the HashSet object. * @group Entries */ forEach(fn: (val: T) => void): void; /** * Iterates over values in the HashSet * @group Iterables */ [Symbol.iterator](): IteratorObject<T, undefined, unknown>; /** * Returns an iterable of [v,v] pairs for every value `v` in the HashSet. * @group Iterables */ entries(): IteratorObject<[T, T], undefined, unknown>; /** * Despite its name, returns an iterable of the values in the HashSet. * @group Iterables */ keys(): IteratorObject<T, undefined, unknown>; /** * Returns an iterable of values in the HashSet. * @group Iterables */ values(): IteratorObject<T, undefined, unknown>; /** * @group Composition * @returns a new HashSet containing all the elements in this HashSet which are not also in the argument. */ difference(other: HashSet): HashSet<T & U>; /** * @group Composition * @returns a new HashSet containing all the elements which are both in this HashSet and in the argument. */ intersection(other: HashSet): HashSet<T & U>; /** * @group Composition * @returns a boolean indicating whether this HashSet has no elements in common with the argument. */ isDisjointFrom(other: HashSet<T>): boolean; /** * @group Composition * @returns a boolean indicating whether all the elements in this HashSet are also in the argument. */ isSubsetOf(other: HashSet<T>): boolean; /** * @group Composition * @returns a boolean indicating whether all the elements in the argument are also in this HashSet. */ isSupersetOf(other: HashSet<T>): boolean; /** * @group Composition * @returns a new HashSet containing all the elements which are in either this HashSet or in the argument, but not in both. */ symmetricDifference(other: HashSet<T>): HashSet<T>; /** * @group Composition * @returns a new HashSet containing all the elements in this HashSet and also all the elements in the argument. */ union(other: HashSet): HashSet<T | U>; /** * Calls a defined callback function on each entry of a HashSet, and returns a HashSet with the collection of unique values returned by each. * * @group Reductions * @param callbackfn A function that accepts up to two arguments. The map method calls the callbackfn function one time for each value in the HashSet. * @param thisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value. */ map<U, C>(callbackfn: (value: T, hashSet: HashSet<T>) => U, thisArg: C): HashSet; /** * Calls a defined callback function on each entry of a HashSet, and returns a HashSet with the collection of unique values returned by each. * * @group Reductions * @param callbackfn A function that accepts up to two arguments. The map method calls the callbackfn function one time for each value in the HashSet. */ map(callbackfn: (value: T, hashSet: HashSet<T>) => U): HashSet; /** * Returns a new HashSet with only the values that meet the condition specified in a callback function. * * @group Reductions * @param predicate A function that accepts up to two arguments. The filter method calls the predicate function one time for each value in the HashSet. * @param thisArg An object to which the this keyword can refer in the predicate function. If thisArg is omitted, undefined is used as the this value. */ filter<S extends T, C>(predicate: (value: T, hashSet: HashSet<T>) => value is S, thisArg: C): HashSet<S>; /** * Returns a new HashSet with only the values that meet the condition specified in a callback function. * * @group Reductions * @param predicate A function that accepts up to two arguments. The filter method calls the predicate function one time for each value in the HashSet. */ filter<S extends T>(predicate: (value: T, hashSet: HashSet<T>) => value is S): HashSet<S>; /** * Returns a new HashSet with only the values that meet the condition specified in a callback function. * * @group Reductions * @param predicate A function that accepts up to two arguments. The filter method calls the predicate function one time for each value in the HashSet. * @param thisArg An object to which the this keyword can refer in the predicate function. If thisArg is omitted, undefined is used as the this value. */ filter<C>(predicate: (value: T, hashSet: HashSet<T>) => boolean, thisArg: C): HashSet<T>; /** * Returns a new HashSet with only the values that meet the condition specified in a callback function. * * @group Reductions * @param predicate A function that accepts up to two arguments. The filter method calls the predicate function one time for each value in the HashSet. */ filter(predicate: (value: T, hashSet: HashSet<T>) => boolean): HashSet<T>; /** * Returns the first value in the HashSet where predicate is true, or undefined * otherwise. * * @group Reductions * @param predicate find calls predicate once for each entry of the HashSet, * until it finds one where predicate returns true. If such an entry is found, find * immediately returns that entry. Otherwise, find returns undefined. * @param thisArg If provided, it will be used as the this value for each invocation of * predicate. If it is not provided, undefined is used instead. */ find<S extends T, C>(predicate: (value: T, hashSet: HashSet<T>) => value is S, thisArg: C): S | undefined; /** * Returns the first value in the HashSet where predicate is true, or undefined * otherwise. * * @group Reductions * @param predicate find calls predicate once for each entry of the HashSet, * until it finds one where predicate returns true. If such an entry is found, find * immediately returns that entry. Otherwise, find returns undefined. */ find<S extends T>(predicate: (value: T, hashSet: HashSet<T>) => value is S): S | undefined; /** * Returns the first value in the HashSet where predicate is true, or undefined * otherwise. * * @group Reductions * @param predicate find calls predicate once for each entry of the HashSet, * until it finds one where predicate returns true. If such an entry is found, find * immediately returns that entry. Otherwise, find returns undefined. * @param thisArg If provided, it will be used as the this value for each invocation of * predicate. If it is not provided, undefined is used instead. */ find<C>(predicate: (value: T, hashSet: HashSet<T>) => boolean, thisArg: C): T | undefined; /** * Returns the first value in the HashSet where predicate is true, or undefined * otherwise. * * @group Reductions * @param predicate find calls predicate once for each entry of the HashSet, * until it finds one where predicate returns true. If such an entry is found, find * immediately returns that entry. Otherwise, find returns undefined. */ find(predicate: (value: T, hashSet: HashSet<T>) => boolean): T | undefined; /** * Calls the specified callback function for all the entries in the HashSet. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function. * @group Reductions * @param callbackfn A function that accepts up to three arguments. The reduce method calls the callbackfn function one time for each entry int he HashSet. */ reduce(callbackfn: (accumulator: T, value: T, hashSet: HashSet<T>) => T): T; /** * Calls the specified callback function for all the entries in the HashSet. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function. * @group Reductions * @param callbackfn A function that accepts up to three arguments. The reduce method calls the callbackfn function one time for each entry in the HashSet. * @param initialValue If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead. */ reduce(callbackfn: (accumulator: U, value: T, hashSet: HashSet<T>) => U, initialValue: U): U; /** * Determines whether the specified callback function returns true for any value in the HashSet * * @group Reductions * @param predicate A function that accepts up to two arguments. The some method calls * the predicate function for each value in the HashSet until the predicate returns a value * which is coercible to the Boolean value true, or until the end of the HashSet iteration. * @param thisArg An object to which the this keyword can refer in the predicate function. * If thisArg is omitted, undefined is used as the this value. */ some<C>(predicate: (this: C, value: T, hashMap: HashSet<T>) => boolean, thisArg: C): boolean; /** * Determines whether the specified callback function returns true for any value in the HashSet * * @group Reductions * @param predicate A function that accepts up to two arguments. The some method calls * the predicate function for each value in the HashSet until the predicate returns a value * which is coercible to the Boolean value true, or until the end of the HashSet iteration. */ some(predicate: (value: T, hashMap: HashSet<T>) => boolean): boolean; /** * Determines whether all the values of a HashSet satisfy the specified test. * * @group Reductions * @param predicate A function that accepts up to two arguments. The every method calls * the predicate function for each value in the HashSet until the predicate returns a value * which is coercible to the Boolean value false, or until the end of the HashSet iteration. * @param thisArg An object to which the this keyword can refer in the predicate function. * If thisArg is omitted, undefined is used as the this value. */ every<S extends T, C>(predicate: (value: T, hashSet: HashSet<T>) => value is S, thisArg: C): this is HashSet<S>; /** * Determines whether all the values of a HashSet satisfy the specified test. * * @group Reductions * @param predicate A function that accepts up to two arguments. The every method calls * the predicate function for each value in the HashSet until the predicate returns a value * which is coercible to the Boolean value false, or until the end of the HashSet iteration. * @param thisArg An object to which the this keyword can refer in the predicate function. * If thisArg is omitted, undefined is used as the this value. */ every<C>(predicate: (value: T, hashSet: HashSet<T>) => boolean, thisArg: C): boolean; /** * Determines whether all the values of a HashSet satisfy the specified test. * * @group Reductions * @param predicate A function that accepts up to two arguments. The every method calls * the predicate function for each value in the array until the predicate returns a value * which is coercible to the Boolean value false, or until the end of the HashSet iteration. */ every<S extends T>(predicate: (value: T, hashSet: HashSet<T>) => value is S): this is HashSet<S>; /** * Determines whether all the values of a HashSet satisfy the specified test. * * @group Reductions * @param predicate A function that accepts up to two arguments. The every method calls * the predicate function for each value in the array until the predicate returns a value * which is coercible to the Boolean value false, or until the end of the HashSet iteration. */ every(predicate: (value: T, hashSet: HashSet<T>) => boolean): boolean; }