Standard Library

class Set<T>

A collection of distinct values of type T, with value semantics.

since 0.1.0-alpha.1linuxwindowswasm

Overview

A set holds each value at most once. Like Array and Map, a set is never changed in place: with, without, union, intersect and except all return a new set. Elements are listed in the order they were first added. Elements are compared the same way Map keys are: by value for numbers, strings and bool, field by field for structs, and by identity for class instances.

Create one with Set() for an empty set, or Set(items) to collect the distinct values of an array. A set is not iterated directly: call toArray() and loop over that.

Description

Set<T> holds distinct values of type T. It has the same purity model as Array and Map: no method changes the receiver, and with and without return a new set. Create one with Set() (or a declaration with no initializer, Set<int> s;), or fold an array into one with Set(items), which drops duplicates.

A set remembers insertion order. toArray() and toString() list the elements in that order, and union puts the elements of the receiver first, followed by the new elements of the argument. toString() produces text such as {3, 1, 2}.

Elements are compared the way Map compares keys: primitives by value, structs field by field, and class instances by identity. A set is built on a map internally, so the same rules and the same ordering apply.

The set algebra methods union, intersect and except each take another set and return a new one. has(x) tests membership, length() counts elements, and isEmpty() is true for an empty set.

Building and combining sets

Set<int> s = Set([3, 1, 3, 2]);
console.writeln(s.toString());
console.writeln(s.length());
console.writeln(s.has(2));
Set<int> bigger = s.with(9);
console.writeln(bigger.toString());
console.writeln(s.toString());
console.writeln(s.without(3).toString());
console.writeln(s.without(77).toString());
Set<int> t = Set([2, 5]);
console.writeln(s.union(t).toString());
console.writeln(s.intersect(t).toString());
console.writeln(s.except(t).toString());
console.writeln(s.toArray());

{3, 1, 2}
3
true
{3, 1, 2, 9}
{3, 1, 2}
{1, 2}
{3, 1, 2}
{3, 1, 2, 5}
{2}
{3, 1}
[3, 1, 2]

Rules

with(x) and without(x) return a new set; the receiver is unchanged. Adding an element that is already present, or removing one that is absent, gives back an equal set.
Rebind to keep a result: seen = seen.with(x);.
A Set prints through toString(). To print one, call console.writeln(s.toString()).
Struct elements are equal when all their fields are; class elements are equal only when they are the same object.

Examples

Rebinding and struct elements

struct Pt { int x; int y; }
Set<int> grown = Set();
grown = grown.with(4).with(4).with(5);
console.writeln(grown.toString());
Set<Pt> pts = Set();
pts = pts.with(Pt(1, 1)).with(Pt(1, 1)).with(Pt(2, 2));
console.writeln(pts.length());
Set<string> none;
console.writeln(none.isEmpty());

{4, 5}
2
true

Examples

Distinct values and set algebra

Set<int> a = Set([1, 2, 2, 3]);
Set<int> b = Set([3, 4]);
console.writeln(a.toString());
console.writeln(a.union(b).toString());
console.writeln(a.intersect(b).toString());
console.writeln(a.except(b).toString());
console.writeln(a.has(2));

{1, 2, 3}
{1, 2, 3, 4}
{3}
{1, 2}
true

Constructors

new

new()

Create an empty set.

Examples

An empty set

Set<string> s = Set();
console.writeln(s.length());
console.writeln(s.with("a").length());
console.writeln(s.length());

0
1
0

new(Array<T> items)

Create a set holding the distinct values of items.

Duplicates are collapsed to their first occurrence, which also decides the order.

Parameters

items: The values to collect.

Examples

From an array with duplicates

Set<string> s = Set(["b", "a", "b", "c", "a"]);
console.writeln(s.length());
console.writeln(s.toArray());

3
[b, a, c]

Methods

except

except(Set<T> o) -> Set<T>

Return a new set of the values that are in this set but not in o.

The values keep the order they have in this set. Neither input is changed.

Parameters

o: The set of values to leave out.

Returns

The difference of the two sets.

Examples

Difference

Set<int> a = Set([1, 2, 3]);
Set<int> b = Set([3, 4]);
console.writeln(a.except(b).toString());
console.writeln(b.except(a).toString());

{1, 2}
{4}

See also: union, intersect

has

has(T v) -> bool

Whether v is in the set.

Parameters

v: The value to test.

Returns

true if the set holds a value equal to v.

Examples

Membership

Set<string> s = Set(["a", "b"]);
console.writeln(s.has("a"));
console.writeln(s.has("z"));

true
false

intersect

intersect(Set<T> o) -> Set<T>

Return a new set of the values that are in both this set and o.

The values keep the order they have in this set. Neither input is changed.

Parameters

o: The other set.

Returns

The intersection of the two sets.

Examples

Intersection

Set<int> a = Set([1, 2, 3]);
Set<int> b = Set([3, 2, 9]);
console.writeln(a.intersect(b).toString());

{2, 3}

See also: union, except

isEmpty

isEmpty() -> bool

Whether the set has no values.

Returns

true when length() is 0.

Examples

Emptiness

Set<int> e = Set();
console.writeln(e.isEmpty());
console.writeln(e.with(1).isEmpty());

true
false

length

length() -> int

The number of distinct values in the set.

Returns

The element count.

Examples

Counting

Set<int> s = Set([1, 1, 2]);
console.writeln(s.length());

toArray

toArray() -> Array<T>

The values as an array, in the order they were first added.

Returns

A new array of the distinct values.

Examples

Looping over a set

Set<string> s = Set(["x", "y", "x"]);
for (string v in s.toArray()) {
    console.writeln(v);
}

x
y

toString

toString() -> string

The set as text, such as {a, b, c}.

The elements appear in the order they were first added, separated by a comma and a space; an empty set is {}. console.writeln(set) does not use this, so call toString (or interpolate the set into a string) to print one.

Returns

The text form of the set.

Examples

Printing a set

Set<int> s = Set([3, 1, 2]);
console.writeln(s.toString());
console.writeln("set: ${s}");
Set<int> empty = Set();
console.writeln(empty.toString());

{3, 1, 2}
set: {3, 1, 2}
{}

union

union(Set<T> o) -> Set<T>

Return a new set of the values that are in this set, in o, or in both.

The values of this set come first, followed by the values only in o. Neither input is changed.

Parameters

o: The other set.

Returns

The union of the two sets.

Examples

Union

Set<int> a = Set([1, 2, 3]);
Set<int> b = Set([3, 4]);
console.writeln(a.union(b).toString());

{1, 2, 3, 4}

See also: intersect, except

with

with(T v) -> Set<T>

Return a new set that also contains v.

If v is already in the set the result has the same elements. The receiver is not changed.

Parameters

v: The value to add.

Returns

A new set including v.

Examples

Adding a value

Set<int> a = Set([1, 2]);
Set<int> b = a.with(3);
console.writeln(a.toString());
console.writeln(b.toString());
console.writeln(b.with(3).length());

{1, 2}
{1, 2, 3}
3

See also: without

without

without(T v) -> Set<T>

Return a new set that does not contain v.

If v is not in the set the result has the same elements. The receiver is not changed.

Parameters

v: The value to remove.

Returns

A new set without v.

Examples

Removing a value

Set<int> a = Set([1, 2, 3]);
console.writeln(a.without(2).toString());
console.writeln(a.without(9).toString());
console.writeln(a.toString());

{1, 3}
{1, 2, 3}
{1, 2, 3}

See also: with

See also

Map — An associative collection from keys of type K to values of type V, with value semantics.
Collections are values — Array, Map and Set never change in place; every changing method returns a new collection, and the idiom for change is to rebind.
Array — An ordered sequence of values of one type, Array<T>, with value semantics.