Set

Set

Extended version of Set (MDN link)

Constructor

new Set(elements, rulesFct) → {Set}

Source:
See:
Use new Set(elements, rulesFct) to create new sets. Alternatively you can use Set.from
Parameters:
Name Type Description
elements array an Array of element.
rulesFct function a function which every element added to the set needs to pass.
Returns:
An instance of the extended version of Set (MDN link)
Type
Set

Methods

(static) cartesian(set1, set2) → {Set}

Source:
See:
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.
Expression: C = A x B = { (a, b) | a ∈ A and b ∈ B}
Note, that A x B ≠ B x A (not commutative)
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] }
Parameters:
Name Type Description
set1 Set A set instance
set2 Set A set instance
Throws:
Throws an error unless both arguments are set instances.
Returns:
a new set instance, that contains the ordered element pairs.
Type
Set

(static) complement(set1, set2) → {Set|*}

Source:
Computes the complement of set B where U is the universe: C = U \ B. This is also known as the "absolute complement".
Parameters:
Name Type Description
set1 U the set to be subtracted from
set2 B the set whose elements will be subtracted from A
Throws:
  • Throws an error if any of the arguments is not a Set instance.
  • Throws an error if any element in B does not occur in U.
Returns:
A new Set with all elements of U minus the elements of B
Type
Set | *

(static) copy(set) → {Set}

Source:
Copies all elements of a given Set instance into a new Set and returns it. It does not deep-clone the elements of the set.
Parameters:
Name Type Description
set Set a set instance from which to copy from
Throws:
Throws an error if the argument is not a Set instance.
Returns:
a new Set instance containing all elements of the source.
Type
Set

(static) difference(set1, set2) → {Set|*}

Source:
Computes the set difference of two sets (subtracts B from A): C = A \ B. This is also known as the "relative complement".
Parameters:
Name Type Description
set1 A the set to be subtracted from
set2 B the set whose elements will be subtracted from A
Throws:
Throws an error if any of the arguments is not a Set instance.
Returns:
A new Set with all elements of A minus the elements of B
Type
Set | *

(static) from(…args) → {Set}

Source:
Creates a new Set from arbitrary arguments without the need of "new" and the array notation.
Examples
Set.from(1,2,3,4,5) // returns Set { 1, 2, 3, 4, 5 }
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 } }
Parameters:
Name Type Attributes Description
args * <repeatable>
 values of any types / length (using comma notation or spread operator)
Returns:
A set containing the given argument values.
Type
Set

(static) intersection(…args) → {Set}

Source:
See:
Creates the set intersection of an arbitrary number of sets. The intersection S of any number of sets Mi is the set whose elements consist of the elements that occur in every single set Mi.
Expression: ∩ M = S
Example: ∩ {M_1, M_2, M_3} = S
Example: ∩ {A, B, C} = S
Example: ∩ {{0,1,2,4}, {1,2,9}, {0,1,2}} = {1,2}
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 }
Parameters:
Name Type Attributes Description
args Set <repeatable>
 an arbitrary list of Set instances
Throws:
Throws an error if any of the arguments is not a Set instance.
Returns:
a Set instance with the shared elements of the given args.
Type
Set

(static) mergeRules(…rules) → {function}

Source:
See:
  • Set.prototype.rules
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).
Parameters:
Name Type Attributes Description
rules function <repeatable>
 An arbitrary amount of (rules-) functions. See Set.prototype.rules for requirements of a rules function.
Throws:
Throws an error if any of the given parameters is not a Function
Returns:
The resulting rules function that can be attached to a set instance.
Type
function

(static) mergeRulesStrict(…rules) → {function}

Source:
See:
  • Set.prototype.rules
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. Attention: If passed rules are mutually exclusive, none given element will pass the test in any circumstance.
Parameters:
Name Type Attributes Description
rules function <repeatable>
 An arbitrary amount of (rules-) functions. See Set.prototype.rules for requirements of a rules function.
Throws:
Throws an error if any of the given parameters is not a Function
Returns:
The resulting rules function that can be attached to a set instance.
Type
function

(static) power(set) → {Set}

Source:
See:
Creates the powerset of a given set instance by using a recursive algorithm (see Wikipedia, section Algorithms). The powerset of a set contains all possible subsets of the set, plus itself and the empty set.
Attention: This method grows exponentially with the size of the given set.
Parameters:
Name Type Description
set Set A Set instance.
Throws:
Throws an error if the given set is not a set instance.
Returns:
a new set instance with all subsets of the given set, plus the given set itself and the empty set.
Type
Set

(static) symDiff(…args) → {Set}

Source:
See:
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.
Expression: C = A Δ B
Example
const a = Set.from(1,2,3)
const b = Set.from(3,4)
Set.symDiff(a, b) // Set { 1, 2, 4 }
Parameters:
Name Type Attributes Description
args Set <repeatable>
 An arbitrary amount of Set instances
Throws:
Throws an error if any of the given arguments is not a set instance.
Returns:
Returns a new Set, that contains only elements.
Type
Set

(static) toSet(value) → {Set}

Source:
Autowraps a value to a Set, unless it is already a Set.
Parameters:
Name Type Description
value * Any arbitrary value
Returns:
A Set containing the value or the value if it is already a Set.
Type
Set

(static) union(…args) → {Set}

Source:
See:
Creates the set union of an arbitrary number of sets. The union S of any number of sets Mi is the set that consists of all elements of each Mi.
Expression: ∪ M = S
Example: ∪ {M_1, M_2, M_3} = S
Example: ∪ {A, B, C} = S
Example: ∪ {{0,4}, {1}, {9}} = {0,1,4,9}
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 }
Parameters:
Name Type Attributes Description
args Set <repeatable>
 an arbitrary list of Set instances
Throws:
Throws an error if any of the arguments is not a Set instance.
Returns:
a Set instance with the unified elements of the given args.
Type
Set

add(value) → {Set}

Source:
See:
Adds a value to the set. If the set already contains the value, nothing happens. Overrides Set.prototype.add.
Parameters:
Name Type Description
value * Required. Any arbitrary value to be added to the set.
Throws:
Error if rules function exists and failed the rules check.
Type
value
Returns:
the Set object
Type
Set

any() → {*}

Source:
Returns an arbitrary element of this set. Basically the first element, retrieved by iterator.next().value will be used.
Returns:
An arbitrary element of the current set that could by of any type, depending on the elements of the set.
Type
*

equal(set) → {boolean}

Source:
See:
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
Examples
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
const a = Set.from({ a:true, b:false })
const b = Set.from({ b:false, a:true })
a.equal(b) // true
Parameters:
Name Type Description
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:
true, if all elements of this set equal to the elements of the given set.
Type
boolean

has(value) → {boolean}

Source:
See:
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
  • primitive types
  • complex types, such as Objects or Arrays
  • nested Objects and cyclic references
  • functions
  • functions with properties attached
  • sets, sets of sets
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.
Example
const a = Set.from({ a:true, b:false })
a.has({ b:false, a:true })  // true
a.has({ b:false, a:false }) // false
Parameters:
Name Type Description
value * The value to be checked.
Returns:
- True, if the value is contained by the set. False, if otherwise.
Type
boolean

intersect(args) → {Set}

Source:
See:
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.
Expression: A ∩ B = S
Example: {0,1,2,4} ∩ {1,2,9} = {1,2}
Example
const A = Set.from(0, 1, 2, 4)
const B = Set.from(1, 2, 9)
A.intersect(B) // Set { 1, 2 }
Parameters:
Name Type Description
args set the other set to intersect with.
Throws:
  • Throws an error if there is not exactly one argument.
  • Throws an error if the argument is not a Set instance.
Returns:
a Set instance with the shared elements of this set and the other set.
Type
Set

isEmpty() → {boolean}

Source:
See:
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
Throws:
Throws an error if any arguments are given.
Returns:
Type
boolean

isSubsetOf(set) → {boolean}

Source:
See:
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.
Expression: A ⊆ B
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.
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
Parameters:
Name Type Description
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:
- true if this set is the subset of the given set, false otherwise
Type
boolean

isSupersetOf(set) → {boolean}

Source:
See:
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.
Expression: A ⊇ B
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
Parameters:
Name Type Description
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:
true if this set is the superset of the given set, otherwise false.
Type
boolean

properSupersetOf(set) → {boolean}

Source:
See:
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.
Expression: A ⊃ B
Parameters:
Name Type Description
set Set A set instance of which this set is checked to be the proper superset.
Returns:
Type
boolean

properSupersetOf(set) → {boolean}

Source:
See:
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.
Expression: A ⊂ B
Parameters:
Name Type Description
set Set A set instance of which this set is checked to be the proper subset.
Returns:
Type
boolean

randomElement() → {*}

Source:
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.
Returns:
An element chosen randomly from the current set that could be of any type, depending on the elements of the set.
Type
*

rules(value) → {function|undefined}

Source:
Pass a function that dictates the rules for elements to be part of this set. Use without args to get the current rules function.
A rules function needs to fulfill the following requirements:
  • Obtain a single element as argument
  • Check, if that element passes certain conditions
  • Return false if the element fails any condition
  • Otherwise return true

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.
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
Parameters:
Name Type Description
value function (Optional) a Function that obtains a single argument and returns either a truthy or falsey value.
Returns:
Returns the current rules Function or undefined if there is on rules function assigned.
Type
function | undefined

toArray() → {Array}

Source:
Creates an (unsorted) array from all elements of this set.
Example
new Set([1, 2, 3, 4]).toArray() // [ 1, 2, 3, 4 ]
Returns:
Array containing all elements of this set in unsorted order.
Type
Array

union(args) → {Set}

Source:
See:
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.
Expression: A ∪ B = C
Example: {1,2} ∪ {1,7,8,9} = {1,2,7,8,9}
Example
const A = Set.from(1, 2)
const B = Set.from(1, 7, 8, 9)
A.union(B) // Set { 1, 2, 7, 8, 9 }
Parameters:
Name Type Description
args set the other set to union with.
Throws:
  • Throws an error if there is not exactly one argument.
  • Throws an error if the argument is not a Set instance.
Returns:
a Set instance with the unified elements of the given args.
Type
Set