Set Library

Stof's standard set library ("Set").

Sets in Stof are ordered and can contain a mixture of types. Within each type, values are ordered as you would expect.

Mixed-Value Ordering:

1. Null values

2. Booleans

3. Numbers

4. Strings

5. Objects - sorted by ID

6. Functions - sorted by ID

7. Arrays/Vectors

8. Tuples

9. Blobs

10. Sets

11. Maps

Common Value Functions

Set.toString(set: set): str

Returns a set converted to a string. This performs the same as "std.pln(set)" and "std.dbg(set)".

#[test("{Number(I64(1)), Number(I64(2)), Number(I64(3))}")]
fn test(): str {
    return set(1, 2, 3).toString();
}

Set.or(set: set, ...): unknown

Returns the first non-empty (null or void) argument, just like the Standard Library "or" function.

#[test]
fn test() {
    let set = self.dne.or(set(1, 2));
    assertEq(set, set(1, 2));
}

Set Functions

Set.append(set: set, other: set): void

Move all values in "other" to this set, leaving "other" empty.

#[test]
fn append() {
    let a: set = set([1, 2]);
    let b = set([2, 3]);
    a.append(b);
    assertEq(a, set(1, 2, 3));
    assertEq(b, set(2, 3));
}

#[test]
fn append_boxed() {
    let a: Box<set> = set([1, 2]);
    let b = box(set([2, 3]));
    a.append(b);
    assertEq(a, set(1, 2, 3));
    assertEq(b, set());
}

Set.clear(set: set): void

Remove all values in this set.

#[test]
fn clear() {
    let a = set(1, 2, 3);
    assertEq(a.len(), 3);
    a.clear();
    assertEq(a.len(), 0);
}

Set.contains(set: set, val: unknown): bool

Does this set contain the value?

#[test]
fn contains() {
    let a = set(('a', 10), true, 'hello', 5);
    assert(a.contains(('a', 10)));
    assert(a.contains(true));
    assertNot(a.contains(false));
    assert(a.contains('hello'));
    assertNot(a.contains('dne'));
    assert(a.contains(5));
    assertNot(a.contains(5.1));
}

Set.first(set: set): unknown

Returns the first value in this set, or null if the set is empty.

#[test]
fn first() {
    let a = set(10, 232, 23, 1, 83, -2, 289);
    assertEq(a.first(), -2);
}

Set.last(set: set): unknown

Returns the last value in this set, or null if the set is empty.

#[test]
fn last() {
    let a = set(10, 232, 23, 1, 83, -2, 289);
    assertEq(a.last(), 289);
}

Set.insert(set: set, val: unknown): bool

Insert a value into this set, returning true if this value is newly inserted.

#[test]
fn insert() {
    let a = set();
    assert(a.insert(10));
    assertNot(a.insert(10));
    assertEq(a, set(10));
}

Set.take(set: set, val: unknown): unknown

Take a value from this set if the set contains it (removing the value from the set).

#[test]
fn take() {
    let a = set(10);
    assertEq(a.take(2), null);
    assertEq(a.take(10), 10);
    assertEq(a.len(), 0);
}

Set.split(set: set, val: unknown): set

Split this set into another set at the given value.

#[test]
fn split() {
    let a = set(0, 1, 2, 3, 4, 5, 6);
    let b = a.split(3);
    assertEq(a, set(0, 1, 2));
    assertEq(b, set(3, 4, 5, 6));

    let c = b.split(0);
    assertEq(b, set());
    assertEq(c, set(3, 4, 5, 6));

    let d = c.split(7);
    assertEq(c, set(3, 4, 5, 6));
    assertEq(d, set());
}

Set.empty(set: set): bool

Is this set empty?

#[test]
fn empty_any() {
    let a = set();
    assert(a.empty());
    assertNot(a.any());

    a.insert(10);
    assert(a.any());
    assertNot(a.empty());
}

Set.any(set: set): bool

Does this set contain any values?

#[test]
fn empty_any() {
    let a = set();
    assert(a.empty());
    assertNot(a.any());

    a.insert(10);
    assert(a.any());
    assertNot(a.empty());
}

Set.len(set: set): int

Returns the length of this set (the number of elements it contains).

#[test]
fn len() {
    let a = set();
    assertEq(a.len(), 0);
    a.insert(10);
    assertEq(a.len(), 1);
}

Set.at(set: set, index: int): unknown

Get a value in this set at the given index.

#[test]
fn at() {
    let a = set(0, 1, 2, 3, 4, 5, 6, 7);
    assertEq(a.at(1), 1);
    assertEq(a[5], 5);

    let count = 0;
    for (val in a) {
        if (first) assertEq(val, 0);
        if (last) assertEq(val, 7);
        count += 1;
    }
    assertEq(count, 8);
}

Set.popFirst(set: set): unknown

Remove the first value in the set and return it.

#[test]
fn pop_first() {
    let a = set(0, 1, 2, 3, 4);
    assertEq(a.popFirst(), 0);
    assertEq(a.popFirst(), 1);
    assertEq(a.len(), 3);
}

Set.popLast(set: set): unknown

Remove the last value in the set and return it.

#[test]
fn pop_last() {
    let a = set(0, 1, 2, 3, 4);
    assertEq(a.popLast(), 4);
    assertEq(a.popLast(), 3);
    assertEq(a.len(), 3);
}

Set.remove(set: set, val: unknown): bool

Remove a value from this set, returning true if the value existed.

#[test]
fn remove() {
    let a = set(1, 2, 3, 4);
    assert(a.remove(3));
    assertNot(a.remove(3));
    assertEq(a.len(), 3);
}

Set.retain(set: set, func: fn): void

Retain only the elements specified by the predicate.

#[test]
fn retain() {
    let a = 0..10 as set;
    a.retain((val: int): bool => val % 2 == 0);
    assertEq(a, set(0, 2, 4, 6, 8));
}

Set.union(set: set, other: set): set

Union this set with another, returning a new set.

#[test]
fn union() {
    let a = set(1, 2);
    let b = set(2, 3);

    let c = a.union(b);
    let d = a + b;
    assertEq(c, d);
    assertEq(c, set(1, 2, 3));
}

Set.difference(set: set, other: set): set

Return a new set which is the difference between this set and another.

#[test]
fn difference() {
    let a = set(1, 2);
    let b = set(2, 3);

    let c = a.difference(b);
    let d = a - b;
    assertEq(c, d);
    assertEq(c, set(1));
}

Set.intersection(set: set, other: set): set

Return a new set which is the intersection between this set and another.

#[test]
fn intersection() {
    let a = set(1, 2);
    let b = set(2, 3);

    let c = a.intersection(b);
    let d = a * b;
    assertEq(c, d);
    assertEq(c, set(2));
}

Set.symmetricDifference(set: set, other: set): set

Return a new set which is the symmetric difference between this set and another.

#[test]
fn symmetric_diff() {
    let a = set(1, 2);
    let b = set(2, 3);

    let c = a.symmetricDifference(b);
    let d = a % b;
    assertEq(c, d);
    assertEq(c, set(1, 3));
}

Set.disjoint(set: set, other: set): bool

Returns true if this set has no elements in common with another.

#[test]
fn disjoint() {
    let a = set(1, 2);
    let b = set(2, 3);
    let c = set(3, 4);
    assert(a.disjoint(c));
    assert(c.disjoint(a));
    assertNot(a.disjoint(b));
    assertNot(b.disjoint(a));
    assertNot(b.disjoint(c));
}

Set.subset(set: set, other: set): bool

Returns true if this set is a subset of another.

#[test]
fn subset() {
    let a = set(1, 2);
    let b = set(1, 2, 3);
    assert(a.subset(b));
    assertNot(b.subset(a));
}

Set.superset(set: set, other: set): bool

Returns true if this set is a superset of another.

#[test]
fn superset() {
    let a = set(1, 2);
    let b = set(1, 2, 3);
    assertNot(a.superset(b));
    assert(b.superset(a));
}