Skip to content

Latest commit

 

History

History
640 lines (495 loc) · 23.3 KB

API.md

File metadata and controls

640 lines (495 loc) · 23.3 KB

Set

Extended version of Set (MDN link)

Kind: global class
See

new Set(elements, rulesFct)

Use new Set(elements, rulesFct) to create new sets. Alternatively you can use Set.from

Returns: Set - An instance of the extended version of Set (MDN link)

Param Type Description
elements array an Array of element.
rulesFct function a function which every element added to the set needs to pass.

set.add(value) ⇒ Set

Adds a value to the set. If the set already contains the value, nothing happens. Overrides Set.prototype.add.

Kind: instance method of Set
Returns: Set - the Set object
Throws:

  • value Error if rules function exists and failed the rules check.

See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/add

Param Type Description
value * Required. Any arbitrary value to be added to the set.

set.has(value) ⇒ boolean

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.

Kind: instance method of Set
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

Param Type Description
value * The value to be checked.

Example

const a = Set.from({ a:true, b:false })
a.has({ b:false, a:true })  // true
a.has({ b:false, a:false }) // false

set.rules(value) ⇒ function | undefined

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.

Kind: instance method of Set
Returns: function | undefined - Returns the current rules Function or undefined if there is on rules function assigned.

Param Type Description
value function (Optional) a Function that obtains a single argument and returns either a truthy or falsey value.

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

set.toArray() ⇒ Array

Creates an (unsorted) array from all elements of this set.

Kind: instance method of Set
Returns: Array - Array containing all elements of this set in unsorted order.
Example

new Set([1, 2, 3, 4]).toArray() // [ 1, 2, 3, 4 ]

set.any() ⇒ *

Returns an arbitrary element of this set. Basically the first element, retrieved by iterator.next().value will be used.

Kind: instance method of Set
Returns: * - An arbitrary element of the current set that could by of any type, depending on the elements of the set.

set.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.

Kind: instance method of Set
Returns: * - An element chosen randomly from the current set that could be of any type, depending on the elements of the set.

set.isSupersetOf(set) ⇒ boolean

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

Kind: instance method of Set
Returns: boolean - true if this set is the superset of the given set, otherwise false.
Throws:

  • Throws an error, if the given set is not a set instance.

See: https://en.wikipedia.org/wiki/Subset

Param Type Description
set Set A set instance of which this set is checked to be the superset.

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

set.isSubsetOf(set) ⇒ boolean

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.

Kind: instance method of Set
Returns: boolean - - true if this set is the subset of the given set, false otherwise
Throws:

  • Throws an error, if the given set is not a set instance.

See

Param Type Description
set Set A set instance of which this set is checked to be the subset.

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

set.properSupersetOf(set) ⇒ boolean

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

Kind: instance method of Set
See: https://en.wikipedia.org/wiki/Subset

Param Type Description
set Set A set instance of which this set is checked to be the proper superset.

set.properSupersetOf(set) ⇒ boolean

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

Kind: instance method of Set
See: https://en.wikipedia.org/wiki/Subset

Param Type Description
set Set A set instance of which this set is checked to be the proper subset.

set.equal(set) ⇒ boolean

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

Kind: instance method of Set
Returns: boolean - true, if all elements of this set equal to the elements of the given set.
Throws:

  • Throws an error if the given paramter is not a Set instance.

See

Param Type Description
set Set A set instance, which this set is to be compared with.

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

set.isEmpty() ⇒ boolean

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 {}.

Kind: instance method of Set
Throws:

  • Throws an error if any arguments are given.

See: https://en.wikipedia.org/wiki/Empty_set
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

set.union(args) ⇒ Set

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}

Kind: instance method of Set
Returns: Set - a Set instance with the unified elements of the given args.
Throws:

  • Throws an error if there is not exactly one argument.
  • Throws an error if the argument is not a Set instance.

See: https://en.wikipedia.org/wiki/Union_(set_theory)#Union_of_two_sets

Param Type Description
args set the other set to union with.

Example

const A = Set.from(1, 2)
const B = Set.from(1, 7, 8, 9)
A.union(B) // Set { 1, 2, 7, 8, 9 }

set.intersect(args) ⇒ Set

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}

Kind: instance method of Set
Returns: Set - a Set instance with the shared elements of this set and the other set.
Throws:

  • Throws an error if there is not exactly one argument.
  • Throws an error if the argument is not a Set instance.

See: https://en.wikipedia.org/wiki/Intersection_(set_theory)#Definition

Param Type Description
args set the other set to intersect with.

Example

const A = Set.from(0, 1, 2, 4)
const B = Set.from(1, 2, 9)
A.intersect(B) // Set { 1, 2 }

Set.from(...args) ⇒ Set

Creates a new Set from arbitrary arguments without the need of "new" and the array notation.

Kind: static method of Set
Returns: Set - A set containing the given argument values.

Param Type Description
...args * values of any types / length (using comma notation or spread operator)

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 } }

Set.toSet(value) ⇒ Set

Autowraps a value to a Set, unless it is already a Set.

Kind: static method of Set
Returns: Set - A Set containing the value or the value if it is already a Set.

Param Type Description
value * Any arbitrary value

Set.copy(set) ⇒ Set

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.

Kind: static method of Set
Returns: Set - a new Set instance containing all elements of the source.
Throws:

  • Throws an error if the argument is not a Set instance.
Param Type Description
set Set a set instance from which to copy from

Set.union(...args) ⇒ Set

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}

Kind: static method of Set
Returns: Set - a Set instance with the unified elements of the given args.
Throws:

  • Throws an error if any of the arguments is not a Set instance.

See: https://en.wikipedia.org/wiki/Union_(set_theory)#Arbitrary_unions

Param Type Description
...args Set an arbitrary list of Set instances

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 }

Set.intersection(...args) ⇒ Set

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}

Kind: static method of Set
Returns: Set - a Set instance with the shared elements of the given args.
Throws:

  • Throws an error if any of the arguments is not a Set instance.

See: https://en.wikipedia.org/wiki/Intersection_(set_theory)#Arbitrary_intersections

Param Type Description
...args Set an arbitrary list of Set instances

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 }

Set.difference(set1, set2) ⇒ Set | *

Computes the set difference of two sets (subtracts B from A): C = A \ B. This is also known as the "relative complement".

Kind: static method of Set
Returns: Set | * - A new Set with all elements of A minus the elements of B
Throws:

  • Throws an error if any of the arguments is not a Set instance.
Param Description
set1 A the set to be subtracted from
set2 B the set whose elements will be subtracted from A

Set.complement(set1, set2) ⇒ Set | *

Computes the complement of set B where U is the universe: C = U \ B. This is also known as the "absolute complement".

Kind: static method of Set
Returns: Set | * - A new Set with all elements of U minus the elements of B
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.
Param Description
set1 U the set to be subtracted from
set2 B the set whose elements will be subtracted from A

Set.symDiff(...args) ⇒ Set

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

Kind: static method of Set
Returns: Set - Returns a new Set, that contains only elements.
Throws:

  • Throws an error if any of the given arguments is not a set instance.

See: https://en.wikipedia.org/wiki/Symmetric_difference

Param Type Description
...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 }

Set.cartesian(set1, set2) ⇒ Set

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)

Kind: static method of Set
Returns: Set - a new set instance, that contains the ordered element pairs.
Throws:

  • Throws an error unless both arguments are set instances.

See: https://en.wikipedia.org/wiki/Cartesian_product

Param Type Description
set1 Set A set instance
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] }

Set.power(set) ⇒ Set

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.

Kind: static method of Set
Returns: Set - a new set instance with all subsets of the given set, plus the given set itself and the empty set.
Throws:

  • Throws an error if the given set is not a set instance.

See: https://en.wikipedia.org/wiki/Power_set

Param Type Description
set Set A Set instance.

Set.mergeRules(...rules) ⇒ function

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).

Kind: static method of Set
Returns: function - The resulting rules function that can be attached to a set instance.
Throws:

  • Throws an error if any of the given parameters is not a Function

See: Set.prototype.rules

Param Type Description
...rules function An arbitrary amount of (rules-) functions. See Set.prototype.rules for requirements of a rules function.

Set.mergeRulesStrict(...rules) ⇒ function

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.

Kind: static method of Set
Returns: function - The resulting rules function that can be attached to a set instance.
Throws:

  • Throws an error if any of the given parameters is not a Function

See: Set.prototype.rules

Param Type Description
...rules function An arbitrary amount of (rules-) functions. See Set.prototype.rules for requirements of a rules function.