Skip to content

set.md

Latest commit

 

History

History
745 lines (450 loc) · 15 KB

set.md

File metadata and controls

745 lines (450 loc) · 15 KB
description A set class providing common operations to create, modify, and query collections of unique values.

Set

A set class providing common operations to create, modify, and query collections of unique values.

Usage

Set = require "mods.Set"

s = Set({ "a" })
print(s:contains("a")) --> true

Functions

Mutation:

Function Description
add(v) Add an element to the set.
clear() Remove all elements from the set.
difference_update(set) Remove elements found in another set (in place).
intersection_update(set) Keep only elements common to both sets (in place).
pop() Remove and return an arbitrary element.
symmetric_difference_update(set) Update the set with elements not shared by both (in place).
update(set) Add all elements from another set (in place).

Copying:

Function Description
copy() Return a shallow copy of the set.
difference(set) Return elements in this set but not in another.
intersection(set) Return elements common to both sets.
remove(v) Remove an element if present, do nothing otherwise.
symmetric_difference(set) Return elements not shared by both sets.
union(set) Return a new set with all elements from both.

Predicates:

Function Description
isdisjoint(set) Return true if sets have no elements in common.
equals(set) Return true when both sets contain exactly the same members.
isempty() Return true if the set has no elements.
issubset(set) Return true if all elements of this set are also in another set.
issuperset(set) Return true if this set contains all elements of another set.

Query:

Function Description
contains(v) Return true if the set contains v.
len() Return the number of elements in the set.

Transform:

Function Description
map(fn) Return a new set by mapping each value.
values() Return a list of all values in the set.

Metamethods:

Function Description
__add(set) Return the union of two sets using +.
__bor(set) Return the union of two sets using |.
__band(set) Return the intersection of two sets using &.
__bxor(set) Return elements present in exactly one set using ^.
__eq(set) Return true if both sets contain exactly the same members using ==.
__le(set) Return true if the left set is a subset of the right set using <=.
__lt(set) Return true if the left set is a proper subset of the right set using <.
__sub(set) Return the difference of two sets using -.

Mutation

In-place operations that mutate the current set.

add(v)

Add an element to the set.

Parameters:

  • v (any): Value to add.

Return:

  • self (T): Current set instance.

Example:

s = Set({ "a" }):add("b") --> s contains "a", "b"

clear()

Remove all elements from the set.

Return:

  • self (T): Current set instance.

Example:

s = Set({ "a", "b" }):clear() --> s is empty

difference_update(set)

Remove elements found in another set (in place).

Parameters:

  • set (T): Other set value.

Return:

  • self (T): Current set instance.

Example:

s = Set({ "a", "b" }):difference_update(Set({ "b" })) --> s contains "a"

intersection_update(set)

Keep only elements common to both sets (in place).

Parameters:

  • set (T): Other set value.

Return:

  • self (T): Current set instance.

Example:

s = Set({ "a", "b" }):intersection_update(Set({ "b", "c" }))
--> s contains "b"

pop()

Remove and return an arbitrary element.

Return:

  • value (any): Removed value, or nil when the set is empty.

Example:

v = Set({ "a", "b" }):pop() --> v is either "a" or "b"

symmetric_difference_update(set)

Update the set with elements not shared by both (in place).

Parameters:

  • set (T): Other set value.

Return:

  • self (T): Current set instance.

Example:

s = Set({ "a", "b" }):symmetric_difference_update(Set({ "b", "c" }))
--> s contains "a", "c"

update(set)

Add all elements from another set (in place).

Parameters:

  • set (T): Other set value.

Return:

  • self (T): Current set instance.

Example:

s = Set({ "a" }):update(Set({ "b" })) --> s contains "a", "b"

Copying

Non-mutating set operations that return new set instances.

copy()

Return a shallow copy of the set.

Return:

  • set (mods.Set): New set.

Example:

c = Set({ "a" }):copy() --> c is a new set with "a"

difference(set)

Return elements in this set but not in another.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • set (mods.Set): New set.

Example:

d = Set({ "a", "b" }):difference(Set({ "b" })) --> d contains "a"

Note

difference is also available as the __sub (-) operator. a:difference(b) is equivalent to a - b.

intersection(set)

Return elements common to both sets.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • set (mods.Set): New set.

Example:

i = Set({ "a", "b" }):intersection(Set({ "b", "c" })) --> i contains "b"

Note

intersection is also available as __band (&) on Lua 5.3+.

remove(v)

Remove an element if present, do nothing otherwise.

Parameters:

  • v (any): Value to remove.

Return:

  • self (T): Current set instance.

Example:

s = Set({ "a", "b" }):remove("b") --> s contains "a"

symmetric_difference(set)

Return elements not shared by both sets.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • set (mods.Set): New set.

Example:

d = Set({ "a", "b" }):symmetric_difference(Set({ "b", "c" }))
--> d contains "a", "c"

Note

symmetric_difference is also available as __bxor (^) on Lua 5.3+.

union(set)

Return a new set with all elements from both.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • set (mods.Set): New set.

Example:

s = Set({ "a" }):union(Set({ "b" })) --> s contains "a", "b"

Note

union is available as __add (+) and __bor (|) on Lua 5.3+. a:union(b) is equivalent to a + b and a | b.

Predicates

Boolean checks about set relationships and emptiness.

isdisjoint(set)

Return true if sets have no elements in common.

Parameters:

  • set (T): Other set value.

Return:

  • ok (boolean): True when sets have no elements in common.

Example:

ok = Set({ "a" }):isdisjoint(Set({ "b" })) --> true

equals(set)

Return true when both sets contain exactly the same members.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • ok (boolean): True when both sets contain the same members.

Example:

a = Set({ "a", "b" })
b = Set({ "b", "a" })
ok = a:equals(b) --> true

Note

equals is also available as the __eq (==) operator. a:equals(b) is equivalent to a == b.

isempty()

Return true if the set has no elements.

Return:

  • ok (boolean): True when the set has no elements.

Example:

empty = Set({}):isempty() --> true

issubset(set)

Return true if all elements of this set are also in another set.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • ok (boolean): True when every element of self exists in set.

Example:

ok = Set({ "a" }):issubset(Set({ "a", "b" })) --> true

Note

issubset is also available as the __le (<=) operator. a:issubset(b) is equivalent to a <= b.

issuperset(set)

Return true if this set contains all elements of another set.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • ok (boolean): True when self contains every element of set.

Example:

ok = Set({ "a", "b" }):issuperset(Set({ "a" })) --> true

Query

Read-only queries for membership and size.

contains(v)

Return true if the set contains v.

Parameters:

  • v (any): Value to check.

Return:

  • ok (boolean): True when v is present in the set.

Example:

ok = Set({ "a", "b" }):contains("a") --> true
ok = Set({ "a", "b" }):contains("z") --> false

len()

Return the number of elements in the set.

Return:

  • count (integer): Element count.

Example:

n = Set({ "a", "b" }):len() --> 2

Transform

Value-to-value transformations and projection helpers.

map(fn)

Return a new set by mapping each value.

Parameters:

  • fn (fun(v:any):any): Mapping function.

Return:

  • set (mods.Set): New set.

Example:

s = Set({ 1, 2 }):map(function(v) return v * 10 end) --> s contains 10, 20

values()

Return a list of all values in the set.

Return:

  • values (mods.List): List of set values.

Example:

values = Set({ "a", "b" }):values() --> { "a", "b" }

Metamethods

__add(set)

Return the union of two sets using +.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • set (mods.Set): New set.

Example:

a = Set({ "a", "b" })
b = Set({ "b", "c" })
u = a + b --> { a = true, b = true, c = true }

Note

__add is the operator form of :union(set).

__bor(set)

Return the union of two sets using |.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • set (mods.Set): New set.

Example:

a = Set({ "a", "b" })
b = Set({ "b", "c" })
u = a | b --> { a = true, b = true, c = true }

Note

__bor is the operator form of :union(set) on Lua 5.3+.

__band(set)

Return the intersection of two sets using &.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • set (mods.Set): New set.

Example:

a = Set({ "a", "b" })
b = Set({ "b", "c" })
i = a & b --> { b = true }

Note

__band is the operator form of :intersection(set) on Lua 5.3+.

__bxor(set)

Return elements present in exactly one set using ^.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • set (mods.Set): New set.

Example:

a = Set({ "a", "b" })
b = Set({ "b", "c" })
d = a ^ b --> { a = true, c = true }

Note

__bxor is the operator form of :symmetric_difference(set) on Lua 5.3+.

__eq(set)

Return true if both sets contain exactly the same members using ==.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • ok (boolean): True when both sets contain the same members.

Example:

ok = Set({ "a", "b" }) == Set({ "b", "a" }) --> true

Note

__eq is the operator form of :equals(set).

__le(set)

Return true if the left set is a subset of the right set using <=.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • ok (boolean): True when self is a subset of set.

Example:

a = Set({ "a" })
b = Set({ "a", "b" })
ok = a <= b --> true

Note

__le is the operator form of :issubset(set).

__lt(set)

Return true if the left set is a proper subset of the right set using <.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • ok (boolean): True when self is a proper subset of set.

Example:

a = Set({ "a" })
b = Set({ "a", "b" })
ok = a < b --> true

__sub(set)

Return the difference of two sets using -.

Parameters:

  • set (mods.Set|table<any,true>): Other set value.

Return:

  • set (mods.Set): New set.

Example:

a = Set({ "a", "b" })
b = Set({ "b", "c" })
d = a - b --> { a = true }

Note

__sub is the operator form of :difference(set).