// //////////////////////////////////////////////////////////////////////////////// //
// MIT License
//
// Copyright (c) 2018 Jan Küster
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
//
// //////////////////////////////////////////////////////////////////////////////// //
/* global self */
// //////////////////////////////////////////////////////////////////////////////// //
// //
// INTERNAL //
// //
// //////////////////////////////////////////////////////////////////////////////// //
/**
* @private detect current environment's globalThis to enable cross-env usage
*/
const scope = (() => {
if (typeof self !== 'undefined') { return self }
if (typeof window !== 'undefined') { return window }
if (typeof global !== 'undefined') { return global }
throw new Error('unable to locate global object')
})()
/**
* @private checks all rules in list tro be a function @private
*/
const checkRules = (rules) => {
rules.forEach(rule => {
if (typeof rule !== 'function') {
throw new Error(`Expected [rule] to be typeof [function], got [${typeof value}]`)
}
})
return true
}
/**
* @private checks, whether an Object is a Set
* @return {boolean}
*/
const isSet = s => Object.prototype.toString.call(s) === '[object Set]'
/**
* @private checks, whether a given value is a Set instance @private
*/
const checkSet = (set) => {
if (!set || !set.constructor || !isSet(set) || !(set instanceof scope.Set)) {
throw new Error(`Expected [set] to be instanceof [${scope.Set.name}], got [${set && set.constructor}]`)
}
return true
}
/**
* @private checks all values to be a Set-instance @private
*/
const checkSets = (sets) => sets.every(s => checkSet(s))
/**
* @private checks arguments length and raises error if not given length
*/
const checkArgsLength = (args, length = 1) => {
if (!args || args.length !== length) {
throw new Error(`The function must be given exactly ${length} argument.`)
}
return true
}
/**
* A decorator which, given an arbitrary set function,
* produces the corresponding binary operation.
* @private
*/
const arbitraryToBinary = (arbitraryFunc) => {
return function binaryFunc (...args) {
checkArgsLength(args, 1)
const set = args[0]
return arbitraryFunc(this, set)
}
}
/**
* @private contains references to the original Set functions
*/
const originals = {
/**
* @private The original Set reference.
*/
constructor: scope.Set,
/**
* @private The original add function.
*/
add: scope.Set.prototype.add,
/**
* @private The original has function reference.
*/
has: scope.Set.prototype.has
}
// //////////////////////////////////////////////////////////////////////////////// //
// //
// OVERRIDES //
// //
// //////////////////////////////////////////////////////////////////////////////// //
scope.Set.prototype.add =
/**
* Adds a value to the set. If the set already contains the value, nothing happens.
* Overrides Set.prototype.add.
* @name Set.prototype.add
* @function
* @throws Error if rules function exists and {value} failed the rules check.
* @param value {*}- Required. Any arbitrary value to be added to the set.
* @returns {Set} the Set object
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/add
*/
function add (value) {
if (this.rulesFct && !this.rulesFct.call(null, value)) {
throw new Error(`Value [${value}] does not match ruleset.`)
}
// in case we add another set, we actually need to (recursively) check
// whether the set is already included, since the original add function
// only checks for uniqueness on a reference level
if (isSet(value) && this.has(value)) {
return this
}
return originals.add.call(this, value)
}
/**
* Resolves an element's inner structure to make it comparable by JSON.stringify.
* @private
*/
function resolve (obj, circ = new originals.constructor([obj])) {
if (typeof obj === 'undefined' ||
typeof obj === 'string' ||
typeof obj === 'number' ||
typeof obj === 'boolean' ||
obj === null) {
return obj
}
// if we have a set we convert it to an Array and continue treating it as such
if (isSet(obj)) {
obj = Array.from(obj)
}
if (typeof obj === 'function') {
const fctObj = { fctStr: String(obj).replace(/\s+/g, '') } // function body to string
// resolve all function properties / attached references
fctObj.refs = Object.getOwnPropertyNames(obj).map(key => originals.has.call(circ, obj[key]) ? 'circular' : resolve(obj[key], circ))
return fctObj
}
const isArray = Array.isArray(obj)
if (typeof obj !== 'object' && !isArray) {
return obj
}
// add obj to check for
// circular references
circ.add(obj)
if (isArray) {
return obj.map(el => originals.has.call(circ, el) ? 'circular' : resolve(el, circ))
}
const copy = {}
Object.getOwnPropertyNames(obj)
.sort((a, b) => a.localeCompare(b))
.forEach(key => {
copy[key] = originals.has.call(circ, obj[key]) ? 'circular' : resolve(obj[key], circ)
})
return copy
}
/**
* Checks if the current set instance contains a given value by recursive deep compare.
* Overrides the original Set.prototype.has.
* The check is recursive and respects
* <ul>
* <li>primitive types</li>
* <li>complex types, such as Objects or Arrays</li>
* <li>nested Objects and cyclic references</li>
* <li>functions</li>
* <li>functions with properties attached</li>
* <li>sets, sets of sets</li>
* </ul>
*
* Note, that functions will be checked against their whitespace-trimmed bodies, which can return false negatives,
* if for example a comment is added to the compare function that not exists in the original function.
*
* @function
* @name Set.prototype.has
* @example
* const a = Set.from({ a:true, b:false })
* a.has({ b:false, a:true }) // true
* a.has({ b:false, a:false }) // false
* @param value {*} - The value to be checked.
* @returns {boolean} - True, if the value is contained by the set. False, if otherwise.
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/has
*/
scope.Set.prototype.has = function has (value) {
const valType = typeof value
if (valType === 'string' || valType === 'number' || valType === 'boolean') {
return originals.has.call(this, value)
}
const iterator = this.values()
let element
while ((element = iterator.next().value) !== undefined) {
const elType = typeof element
if (elType !== valType) {
return false
}
const setCompare = isSet(element) && isSet(value)
// if both point to the same reference
if (element === value) {
return true
} else
// if we want to check if this set has a set with the
// same elements as the given set in the argument,
// we need to check for equality of all elements of this set
// and the argument set
if (setCompare && element.equal(value)) {
return true
} else
// - if we want to check if ordered pairs (represented as arrays),
// are equal, we resolve their children and compare their strings.
// - For all nested objects we recursively create a "sorted"
// version of both and compare their strings.
// - functions are string-ed and their properties are resolved
// like objects
if ((elType === 'function' && valType === 'function') ||
(!setCompare && elType === 'object' && valType === 'object') ||
(Array.isArray(element) && Array.isArray(value))) {
const sortedElmnt = resolve(element)
const sortedValue = resolve(value)
if (JSON.stringify(sortedElmnt) === JSON.stringify(sortedValue)) {
return true
}
}
}
// and if nothing has matched, we assume
// that it is not contained in this set
return false
}
// //////////////////////////////////////////////////////////////////////////////// //
// //
// PROTOTYPES //
// //
// //////////////////////////////////////////////////////////////////////////////// //
scope.Set.prototype.rules =
/**
* Pass a function that dictates the rules for elements to be part of this set.
* Use without args to get the current rules function.
* <br>
* A rules function needs to fulfill the following requirements:
* <ul>
* <li>Obtain a single element as argument</li>
* <li>Check, if that element passes certain conditions</li>
* <li>Return false if the element fails any condition</li>
* <li>Otherwise return true</li>
* </ul>
* <br>
* If a set contains a rules function (or a merge of many rules functions), the element will only be added to the set,
* if it passes the rules check.
* @function
* @name Set.prototype.rules
* @example
* const isInt = n => Number.isInteger(n)
* const integers = Set.from()
* integers.rules(isInt)
* integers.add(1) // OK, no error
* integers.add(1.5) // throws error!
* integers.add(1.0) // OK, because 1.0 === 1 in JS Number
* @param value {Function} (Optional) a Function that obtains a single argument and returns either a truthy or falsey value.
* @returns {Function|undefined} Returns the current rules Function or undefined if there is on rules function assigned.
*/
function rules (value) {
if (value) {
checkRules([value])
this.rulesFct = value
}
return this.rulesFct
}
scope.Set.prototype.toArray =
/**
* Creates an (unsorted) array from all elements of this set.
* @function
* @name Set.prototype.toArray
* @example new Set([1, 2, 3, 4]).toArray() // [ 1, 2, 3, 4 ]
* @returns {Array} Array containing all elements of this set in unsorted order.
*/
function toArray () {
const self = this
const out = []
out.length = self.size
let count = 0
self.forEach(value => {
out[count++] = value
})
return out
}
scope.Set.prototype.any =
/**
* Returns an arbitrary element of this set.
* Basically the first element, retrieved by iterator.next().value will be used.
* @function
* @name Set.prototype.any
* @returns {*} An arbitrary element of the current set that could by of any type, depending on the elements of the set.
*/
function any () {
const self = this
const iterator = self.values()
return iterator.next().value
}
scope.Set.prototype.randomElement =
/**
* Returns a random element of this set.
* One element of this set is chosen at random and returned. The probability distribution is uniform. Math.random() is used internally for this purpose.
* @function
* @name Set.prototype.randomElement
* @returns {*} An element chosen randomly from the current set that could be of any type, depending on the elements of the set.
*/
function randomElementUnary () {
const array = this.toArray()
const randomIndex = Math.floor(Math.random() * array.length)
return array[randomIndex]
}
scope.Set.prototype.isSupersetOf =
/**
* Checks, whether the current set (this) is a superset of the given set.
* A set A is superset of set B, if A contains all elements of B.
* <br>
* Expression: <code>A ⊇ B</code>
* @function
* @name Set.prototype.isSupersetOf
* @example
* const a = Set.from(1,2,3,4)
* const b = Set.from(1,2,3)
* const c = Set.from(1,2,3,4,5)
* a.isSupersetOf(b) // true
* a.isSupersetOf(c) // false
* c.isSupersetOf(b) // true
* @param set {Set} - A set instance of which this set is checked to be the superset.
* @throws Throws an error, if the given set is not a set instance.
* @returns {boolean} true if this set is the superset of the given set, otherwise false.
* @see https://en.wikipedia.org/wiki/Subset
*/
function isSupersetOf (set) {
const iterator = set.values()
let value
while ((value = iterator.next().value) !== undefined) {
if (!this.has(value)) return false
}
return true
}
scope.Set.prototype.isSubsetOf =
/**
* Checks, whether the current set (this) is a subset of the given set.
* A set A is subset of set B, if B contains all elements of A.
* <br>
* Expression: <code>A ⊆ B</code>
* <br>
* If their sizes are also equal, they can be assumed as equal.
* If their sizes are not equal, then A is called a proper subset of B.
* @function
* @name Set.prototype.isSubsetOf
* @example
* const a = Set.from(1,2,3,4)
* const b = Set.from(1,2,3)
* const c = Set.from(1,2,3,4,5)
* a.isSubsetOf(b) // false
* b.isSubsetOf(c) // true
* c.isSubsetOf(a) // false
* @param set {Set} - A set instance of which this set is checked to be the subset.
* @throws Throws an error, if the given set is not a set instance.
* @returns {boolean} - true if this set is the subset of the given set, false otherwise
* @see https://en.wikipedia.org/wiki/Subset
* @see Set.prototype.equal
* @see Set.prototype.isProperSubsetOf
*/
function isSubsetOf (set) {
return set.isSupersetOf(this)
}
scope.Set.prototype.properSupersetOf =
/**
* Checks, whether the current set (this) is a proper superset of the given set.
* A set A is a proper subset of set B, if A contains all elements of B and their sizes are not equal.
* <br>
* Expression: <code>A ⊃ B</code>
* @function
* @name Set.prototype.properSupersetOf
* @param set {Set} - A set instance of which this set is checked to be the proper superset.
* @returns {boolean}
* @see https://en.wikipedia.org/wiki/Subset
*/
function isProperSupersetOf (set) {
return this.size !== set.size && this.isSupersetOf(set)
}
scope.Set.prototype.properSubsetOf =
/**
* Checks, whether the current set (this) is a proper subset of the given set.
* A set A is a proper subset of set B, if B contains all elements of A and their sizes are not equal.
* <br>
* Expression: <code>A ⊂ B</code>
* @function
* @name Set.prototype.properSupersetOf
* @param set {Set} - A set instance of which this set is checked to be the proper subset.
* @returns {boolean}
* @see https://en.wikipedia.org/wiki/Subset
*/
function isProperSubsetOf (set) {
return this.size !== set.size && this.isSubsetOf(set)
}
scope.Set.prototype.equal =
/**
* Checks, whether two sets are equal in terms of their contained elements.
* Note: This implementation uses a deep object comparison in order to check for "sameness".
* This allows also to check equality for more complex / nested structures without the restriction of interpreting
* "sameness" as "being the exact same instance". If such an equality is desired, please use Set.prototype.equalSrict
* @function
* @name Set.prototype.equal
* @example
* const a = Set.from(1,2,3)
* const b = Set.from(1,2,3.0) // note that 3.0 will evaluate to 3 here!
* a === b // false
* a.equal(b) // true
* @example
* const a = Set.from({ a:true, b:false })
* const b = Set.from({ b:false, a:true })
* a.equal(b) // true
* @param set {Set} - A set instance, which this set is to be compared with.
* @throws Throws an error if the given paramter is not a Set instance.
* @returns {boolean} true, if all elements of this set equal to the elements of the given set.
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness
* @see Set.prototype.isSubsetOf
*/
function equal (set) {
checkSet(set)
if (this.size !== set.size) {
return false
}
return this.isSubsetOf(set)
}
scope.Set.prototype.isEmpty =
/**
* Checks whether this set is the empty set.
* A Set is empty if and only if it has no elements. This is the same thing as having size (cardinality) 0. The empty set is often denoted ∅ or {}.
* @example
* const A = new Set()
* const B = new Set([])
* const C = Set.from()
* const D = Set.from(7)
* A.isEmpty() // true
* B.isEmpty() // true
* C.isEmpty() // true
* D.isEmpty() // false
* @function
* @name Set.prototype.isEmpty
* @throws Throws an error if any arguments are given.
* @returns {boolean}
* @see https://en.wikipedia.org/wiki/Empty_set
*/
function isEmptyUnary () {
return this.size === 0
}
// //////////////////////////////////////////////////////////////////////////////// //
// //
// CONSTRUCTOR //
// //
// //////////////////////////////////////////////////////////////////////////////// //
scope.Set =
/**
* Use <code>new Set(elements, rulesFct)</code> to create new sets. Alternatively you can use <code>Set.from</code>
* @class
* @name Set
* @classdesc Extended version of <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set">Set (MDN link)</a>
* @param elements {array} - an Array of element.
* @param rulesFct {function} - a function which every element added to the set needs to pass.
* @see Set.from
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
* @returns {Set} An instance of the extended version of <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set">Set (MDN link)</a>
*/
function Set (elements, rulesFct) {
const original = new originals.constructor()
if (rulesFct) {
original.rules(rulesFct)
}
if (elements) { elements.forEach(element => original.add(element)) }
return original
}
/**
* The prototype is the original Set constructor
* @type {contains}
*/
scope.Set.prototype = originals.constructor.prototype
// //////////////////////////////////////////////////////////////////////////////// //
// //
// STATICS //
// //
// //////////////////////////////////////////////////////////////////////////////// //
scope.Set.from =
/**
* Creates a new Set from arbitrary arguments without the need of "new" and the array notation.
* @function
* @name Set.from
* @example Set.from(1,2,3,4,5) // returns Set { 1, 2, 3, 4, 5 }
* @example
* const ints = Set.from(1,2,3)
* const flts = Set.from(4.5, 5.6, 6.7)
* Set.from(ints, flts) // returns Set { Set {1, 2, 3}, Set { 4.5, 5.6, 6.7 } }
* @param args {...*} - values of any types / length (using comma notation or spread operator)
* @returns {Set} A set containing the given argument values.
*/
function from (...args) {
return new Set([...args])
}
scope.Set.toSet =
/**
* Autowraps a value to a Set, unless it is already a Set.
* @function
* @name Set.toSet
* @param value {*} - Any arbitrary value
* @returns {Set} A Set containing the value or the value if it is already a Set.
*/
function toSet (value) {
return value instanceof Set ? value : Set.from(value)
}
scope.Set.copy =
/**
* Copies all elements of a given Set instance into a new Set and returns it.
* <strong>It does not deep-clone the elements of the set.</strong>
* @function
* @name Set.copy
* @throws Throws an error if the argument is not a Set instance.
* @param set {Set} a set instance from which to copy from
* @returns {Set} a new Set instance containing all elements of the source.
*/
function copy (set) {
checkSet(set)
const c = new Set()
set.forEach(el => c.add(el))
return c
}
scope.Set.union =
/**
* Creates the set union of an arbitrary number of sets.
* The union S of any number of sets M<sub>i</sub> is the set that consists of all elements of each M<sub>i</sub>.
* <br>Expression: <code>∪ M = S</code>
* <br>Example: <code>∪ {M_1, M_2, M_3} = S</code>
* <br>Example: <code>∪ {A, B, C} = S</code>
* <br>Example: <code>∪ {{0,4}, {1}, {9}} = {0,1,4,9}</code>
* @example
* const A = Set.from(0, 4)
* const B = Set.from(1)
* const C = Set.from(9)
* Set.union(A, B, C) // Set { 0, 1, 4, 9 }
* const M = [A, B, C]
* Set.union(...M) // Set { 0, 1, 4, 9 }
* @name Set.union
* @function
* @param args {...Set} - an arbitrary list of Set instances
* @throws Throws an error if any of the arguments is not a Set instance.
* @returns {Set} a Set instance with the unified elements of the given args.
* @see https://en.wikipedia.org/wiki/Union_(set_theory)#Arbitrary_unions
*/
function unionArbitrary (...args) {
checkSets(args)
const set3 = new Set()
args.forEach(set => set.forEach(value => set3.add(value)))
return set3
}
/**
* Creates the set union of two sets.
* The union of A and B is the set C that consists of all elements of A and B.
* <br>Expression: <code>A ∪ B = C</code>
* <br>Example: <code>{1,2} ∪ {1,7,8,9} = {1,2,7,8,9}</code>
* @example
* const A = Set.from(1, 2)
* const B = Set.from(1, 7, 8, 9)
* A.union(B) // Set { 1, 2, 7, 8, 9 }
* @name Set.prototype.union
* @function
* @param args {set} - the other set to union with.
* @throws Throws an error if there is not exactly one argument.
* @throws Throws an error if the argument is not a Set instance.
* @returns {Set} a Set instance with the unified elements of the given args.
* @see https://en.wikipedia.org/wiki/Union_(set_theory)#Union_of_two_sets
*/
scope.Set.prototype.union = arbitraryToBinary(scope.Set.union)
scope.Set.intersection =
/**
* Creates the set intersection of an arbitrary number of sets.
* The intersection S of any number of sets M<sub>i</sub> is the set whose elements consist of the elements that occur in every single set M<sub>i</sub>.
* <br>Expression: <code>∩ M = S</code>
* <br>Example: <code>∩ {M_1, M_2, M_3} = S</code>
* <br>Example: <code>∩ {A, B, C} = S</code>
* <br>Example: <code>∩ {{0,1,2,4}, {1,2,9}, {0,1,2}} = {1,2}</code>
* @example
* const A = Set.from(0, 1, 2, 4)
* const B = Set.from(1, 2, 9)
* const C = Set.from(0, 1, 2)
* Set.intersection(A, B, C) // Set { 1, 2 }
* const M = [A, B, C]
* Set.intersection(...M) // Set { 1, 2 }
* @name Set.intersection
* @function
* @param args {...Set}- an arbitrary list of Set instances
* @throws Throws an error if any of the arguments is not a Set instance.
* @returns {Set} a Set instance with the shared elements of the given args.
* @see https://en.wikipedia.org/wiki/Intersection_(set_theory)#Arbitrary_intersections
*/
function intersectionArbitrary (...args) {
checkSets(args)
if (!args || args.length === 0) {
throw new Error('The intersection operator currently does not support 0 arguments.')
}
const set3 = new Set()
const minimumSet = args.reduce((prev, curr) => {
return (prev.size < curr.size) ? prev : curr
}, args[0])
for (const value of minimumSet) {
if (args.every(compare => compare.has(value))) {
set3.add(value)
}
}
return set3
}
/**
* Creates the set intersection of two sets.
* The intersection S of sets A and B is the set whose elements consist of the elements that occur in both A and B.
* <br>Expression: <code>A ∩ B = S</code>
* <br>Example: <code>{0,1,2,4} ∩ {1,2,9} = {1,2}</code>
* @example
* const A = Set.from(0, 1, 2, 4)
* const B = Set.from(1, 2, 9)
* A.intersect(B) // Set { 1, 2 }
* @name Set.prototype.intersect
* @function
* @param args {set} - the other set to intersect with.
* @throws Throws an error if there is not exactly one argument.
* @throws Throws an error if the argument is not a Set instance.
* @returns {Set} a Set instance with the shared elements of this set and the other set.
* @see https://en.wikipedia.org/wiki/Intersection_(set_theory)#Definition
*/
scope.Set.prototype.intersect = arbitraryToBinary(scope.Set.intersection)
scope.Set.difference =
/**
* Computes the set difference of two sets (subtracts B from A): <code>C = A \ B</code>. This is also known as the "relative complement".
*
* @name Set.difference
* @function
* @throws Throws an error if any of the arguments is not a Set instance.
* @param set1 - A the set to be subtracted from
* @param set2 - B the set whose elements will be subtracted from A
* @returns {Set|*} A new Set with all elements of A minus the elements of B
*/
function difference (set1, set2) {
checkSet(set1)
checkSet(set2)
const set3 = new Set([])
set1.forEach(value => {
if (!set2.has(value)) {
set3.add(value)
}
})
return set3
}
scope.Set.complement =
/**
* Computes the complement of set B where U is the universe: <code>C = U \ B</code>. This is also known as the "absolute complement".
*
* @name Set.complement
* @function
* @throws Throws an error if any of the arguments is not a Set instance.
* @throws Throws an error if any element in B does not occur in U.
* @param set1 - U the set to be subtracted from
* @param set2 - B the set whose elements will be subtracted from A
* @returns {Set|*} A new Set with all elements of U minus the elements of B
*/
function complement (set1, set2) {
checkSet(set1)
checkSet(set2)
if (!set1.isSupersetOf(set2)) {
throw new Error('[set2] has an element which is not in the universe [set1].')
}
return Set.difference(set1, set2)
}
/**
*
* @private
*/
function symDiff (set1, set2) {
const set3 = new Set()
function addToSet (source, compare, target) {
source.forEach(value => {
if (!compare.has(value)) {
target.add(value)
}
})
}
addToSet(set1, set2, set3)
addToSet(set2, set1, set3)
return set3
}
scope.Set.symDiff =
/**
* Creates the symmetric difference (disjunctive union) of an arbitrary number (2 .. n) of sets.
* The symmetric difference of two sets A and B is a set, that contains only those elements,
* which are in either of the sets and not in their intersection.
* The symmetric difference is commutative and associative, which is why arbitrary number of sets can be used as input
* for a sequencial-computed symmetric difference.
* <br>
* Expression: <code>C = A Δ B</code>
*
* @function
* @name Set.symDiff
* @param args {...Set}- An arbitrary amount of Set instances
* @example
* const a = Set.from(1,2,3)
* const b = Set.from(3,4)
* Set.symDiff(a, b) // Set { 1, 2, 4 }
* @throws Throws an error if any of the given arguments is not a set instance.
* @returns {Set} Returns a new Set, that contains only elements.
* @see https://en.wikipedia.org/wiki/Symmetric_difference
*/
function symmetricDifference (...args) {
args.forEach(arg => checkSet(arg))
if (args.length === 2) {
return symDiff(...args)
}
let set3 = symDiff(args.shift(), args.shift())
while (args.length > 0) {
set3 = symDiff(set3, args.shift())
}
return set3
}
scope.Set.cartesian =
/**
* Creates the cartesian product of two given sets.
* The cartesian product of two sets A and B is the set of all ordered pairs (a, b) where a ∈ A and b ∈ B.
* <br>
* Expression: <code>C = A x B = { (a, b) | a ∈ A and b ∈ B}</code>
* <br>
* Note, that <code>A x B ≠ B x A</code> (not commutative)
* @function
* @name Set.cartesian
* @param set1 {Set} - A set instance
* @param set2 {Set} - A set instance
* @example
* const a = Set.from(1,2)
* const b = Set.from(3,4)
* Set.cartesian(a, b) // Set { [1, 3], [1, 4], [2, 3], [2, 4] }
* Set.cartesian(b, a) // Set { [3, 1], [3, 2], [4, 1], [4, 2] }
* @throws Throws an error unless both arguments are set instances.
* @return {Set} a new set instance, that contains the ordered element pairs.
* @see https://en.wikipedia.org/wiki/Cartesian_product
*/
function cartesianProduct (set1, set2) {
checkSet(set1)
checkSet(set2)
const set3 = new Set()
set1.forEach(value1 => set2.forEach(value2 => set3.add([value1, value2])))
return set3
}
/**
* https://en.wikipedia.org/wiki/Power_set
* @private
*/
function subsets (S, output = new Set()) {
checkSet(S)
if (S.size === 0) {
return Set.from(S)
}
const it = S.values()
let result = it.next()
while (!result.done) {
const e = result.value
const eSet = Set.from(e)
// get difference between first element and the rest
const diff = Set.difference(S, eSet)
output.add(diff)
// recursion: get subsets for the difference, too
const subs = subsets(diff)
subs.forEach(entry => output.add(entry))
result = it.next()
}
return output
}
scope.Set.power =
/**
* Creates the powerset of a given set instance by using a recursive algorithm (see <a href="https://en.wikipedia.org/wiki/Power_set">Wikipedia</a>, section Algorithms).
* The powerset of a set contains all possible subsets of the set, plus itself and the empty set.
* <br>
* <strong>Attention:</strong> This method grows exponentially with the size of the given set.
* @name Set.power
* @function
* @param set {Set} - A Set instance.
* @throws
* Throws an error if the given set is not a set instance.
* @returns {Set} a new set instance with all subsets of the given set, plus the given set itself and the empty set.
* @see https://en.wikipedia.org/wiki/Power_set
*/
function powerSet (set) {
checkSet(set)
const subs = subsets(set)
subs.add(new Set())
subs.add(set)
set.forEach(value => subs.add(Set.from(value)))
return subs
}
/** @private **/
const mergeRulesAny = (strict, rules) => {
const targetFn = strict
? rules.every
: rules.some
return value => {
const passed = targetFn.call(rules, rule => rule.call(value))
if (!passed) {
throw new Error(`Value [${value}] does not match any rule of the ruleset.`)
}
return true
}
}
scope.Set.mergeRules =
/**
* Merges two rules functions with a strict pass concept.
* The resulting function requires the given element to pass at least one of the given functions (logical OR).
* @function
* @name Set.mergeRules
* @throws Throws an error if any of the given parameters is not a Function
* @param rules {...Function} - An arbitrary amount of (rules-) functions. See {@link Set.prototype.rules} for requirements of a rules function.
* @returns {function(*=): boolean} The resulting rules function that can be attached to a set instance.
* @see Set.prototype.rules
*
*/
function mergeRules (...rules) {
checkRules(rules)
return mergeRulesAny(false, rules)
}
scope.Set.mergeRulesStrict =
/**
* Merges two rules functions with a strict pass concept.
* The resulting function requires the given element to pass all of the given functions (logical AND).
* Thus, if the element fails one, it fails all.
* <strong>Attention:</strong> If passed rules are mutually exclusive, none given element will pass the test in any circumstance.
* @function
* @name Set.mergeRulesStrict
* @throws Throws an error if any of the given parameters is not a Function
* @param rules {...Function} - An arbitrary amount of (rules-) functions. See {@link Set.prototype.rules} for requirements of a rules function.
* @returns {function(*=): boolean} The resulting rules function that can be attached to a set instance.
* @see Set.prototype.rules
*/
function mergeRulesStrict (...rules) {
checkRules(rules)
return mergeRulesAny(true, rules)
}
/**
* Flag to indicate the presence of this polyfill
* @type {boolean}
* @private
*/
scope.Set.__isExtended__ = true