Map Library

Stof's standard map library ("Map").

Maps 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

Map.toString(map: map): str

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

#[test('{String("a"): Number(I64(1)), String("b"): Number(I64(2))}')]
fn test(): str {
    return map(("a", 1), ("b", 2)).toString();
}

Map.or(map: map, ...): unknown

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

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

Map Functions

Map.append(map: map, other: map): void

Move all elements from another map into this map, leaving the other map empty.

#[test]
fn append() {
    let a = box(map([("a", "A")]));
    let b = map([("b", "B")]);
    b.append(a); // unboxed a will copy and a.len() will be 1 still, boxed passes by ref
    assertEq(a.len(), 0);
    assertEq(b.len(), 2);
    assertEq(b.first(), ("a", "A"));
    assertEq(b.last(), ("b", "B"));
}

Map.clear(map: map): void

Clear this map, removing all elements.

#[test]
fn clear() {
    let a = map([("a", "A"), (10, 100)]);
    a.clear();
    assertEq(a.len(), 0);
    assert(a.empty());
}

Map.contains(map: map, key: unknown): bool

Does this map contain this key?

#[test]
fn contains() {
    let a = map(("a", "A"), (42, "meaning of life"));
    assert(a.contains("a"));
    assert(a.contains(42));
    assertNot(a.contains("b"));
}

Map.first(map: map): (unknown, unknown)

Returns the first key-value pair in this ordered map.

#[test]
fn first() {
    let a = map([(10, 10), (9, 9), (8, 8), (7, 7)]);
    assertEq(a.first(), (7, 7));
}

Map.last(map: map): (unknown, unknown)

Returns the last key-value pair in this ordered map.

#[test]
fn last() {
    let a = map([(10, 10), (9, 9), (8, 8), (7, 7)]);
    assertEq(a.last(), (10, 10));
}

Map.get(map: map, key: unknown): unknown

Get a value from this map, or null if the map does not contain this key.

#[test]
fn get() {
    let a = map(
        (10, 22),
        (42, "meaning of life"),
        ("hello", "dude"),
        (("a", "b"), ("A", "B")));
        
    assertEq(a.get(10), 22);
    assertEq(a.get(42), "meaning of life");
    assertEq(a.get("hello"), "dude");
    assertEq(a.get("dne"), null);

    assertEq(a.get(("a", "b")), ("A", "B"));
    assertEq(a.get(("A", "b")), null);
    assertEq(a.get(("a", "a")), null);
}

Map.insert(map: map, key: unknown, value: unknown): unknown

Insert a key-value pair into this map, returning the old value if the map already contains this key, null otherwise.

#[test]
fn insert() {
    let a = box(map());
    
    a.insert("a", "A");
    a.insert(true, "hello");
    a.insert(1, 1);
    a.insert(44.2, 54.1);
    
    assertEq(a.len(), 4);
    assertEq(a.get("a"), "A");
    assertEq(a.get("b"), null);
    assertEq(a.get(true), "hello");
}

Map.empty(map: map): bool

Is this map empty?

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

    a.insert(0, "a");
    assertNot(a.empty());
    assert(a.any());
}

Map.any(map: map): bool

Does this map contain any items?

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

    a.insert(0, "a");
    assertNot(a.empty());
    assert(a.any());
}

Map.keys(map: map): vec

Returns a vector containing this map's keys (sorted).

#[test]
fn keys_values() {
    let a = map([(3, 6), (1, 4), (2, 5)]);
    assertEq(a.keys(), [1, 2, 3]);
    assertEq(a.values(), [4, 5, 6]);
}

Map.values(map: map): vec

Returns a vector containing this map's values (sorted according to keys).

#[test]
fn keys_values() {
    let a = map([(3, 6), (1, 4), (2, 5)]);
    assertEq(a.keys(), [1, 2, 3]);
    assertEq(a.values(), [4, 5, 6]);
}

Map.len(map: map): int

Returns the number of items contained within this map.

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

Map.at(map: map, index: int | unknown): (unknown, unknown)

Return an item within this map at a specific index. If the index is numerical, it will be interpreted as a position within the ordered map. If the index is any other value, the behavior mimics that of the "get" function but returns a key-value pair if the item exists (null otherwise).

#[test]
fn at() {
    // recommended that you use 'get', but 'at' works for non-numerical keys also
    let a = map((3, 6), (1, 4), (2, 5));
    
    assertEq(a[0], (1, 4));
    assertEq(a.at(1), (2, 5));
    assertEq(a[2], (3, 6));

    let count = 0;
    for (item in a) {
        count += 1;
        if (first) assertEq(item, (1, 4));
        else if (last) assertEq(item, (3, 6));
        else assertEq(item, (2, 5));
    }
    assertEq(count, 3);
}

#[test]
fn at_non_index() {
    let a = map([(3, 6), (1, 4), ("hi", 5)]);
    assertEq(a["hi"], ("hi", 5));
}

Map.popFirst(map: map): (unknown, unknown)

Remove the first item of this map and return it.

#[test]
fn pop_first() {
    let a = map([(3, 6), (1, 4), (2, 5)]);
    assertEq(a.popFirst(), (1, 4));
    assertEq(a.len(), 2);
    assertEq(a.first(), (2, 5));
}

Map.popLast(map: map): (unknown, unknown)

Remove the last item of this map and return it.

#[test]
fn pop_last() {
    let a = map([(3, 6), (1, 4), (2, 5)]);
    assertEq(a.popLast(), (3, 6));
    assertEq(a.len(), 2);
    assertEq(a.last(), (2, 5));
}

Map.remove(map: map, key: unknown): unknown

Remove the item in this map with the given key and return it's value, or null if the item does not exist.

#[test]
fn remove() {
    let a = map([(3, 6), (1, 4), (2, 5), ("hi", 100)]);
    
    let val: int = a.remove("hi");
    assertEq(val, 100);
    
    val = a.remove("hi");
    assertNull(val);

    val = a.remove(3);
    assertEq(val, 6);

    assertEq(a.len(), 2);
    assertEq(a.first(), (1, 4));
    assertEq(a.last(), (2, 5));
}

Map.retain(map: map, predicate: fn): void

Retain only the elements in this map specified by the predicate. The predicate function takes two parameters (key and value) and returns a boolean, indicating whether to keep or remove the key-value pair from the map.

#[test]
fn retain() {
    let a = map((3, 6), (1, 4), (2, 5), ("hi", 100));
    a.retain((key: unknown, value: unknown): bool => (typeof key) == 'str');
    assertEq(a.len(), 1);
    assertEq(a.first(), a.last());
    assertEq(a.first(), ("hi", 100));
}

Map Operations

Union

#[test]
fn union() {
    let a = map([('a', 'A')]);
    let b = map([('b', 'B')]);
    let c = a + b; // union operation
    assertEq(c.toString(), '{String("a"): String("A"), String("b"): String("B")}');
}

Difference

#[test]
fn diff_map() {
    let a = map([('a', 'A'), ('b', 'B')]);
    let b = map([('b', 'B')]);
    let c = a - b;
    assertEq(c.toString(), '{String("a"): String("A")}');
}

#[test]
fn diff_vec() {
    let a = map([('a', 'A'), ('b', 'B')]);
    let b = ['b'];
    let c = a - b;
    assertEq(c.toString(), '{String("a"): String("A")}');
}

Intersection

#[test]
fn intersect_map() {
    let a = map([('a', 'A'), ('b', 'B'), ('c', 'C')]);
    let b = map([('c', 'C'), ('d', 'D'), ('e', 'E')]);
    let c = a * b;
    assertEq(c.toString(), '{String("c"): String("C")}');
}

#[test]
fn intersect_vec() {
    let a = map([('a', 'A'), ('b', 'B'), ('c', 'C')]);
    let b = vec('c', 'd', 'e');
    let c = a * b;
    assertEq(c.toString(), '{String("c"): String("C")}');
}

Symmetric Difference

#[test]
fn symmetric_difference() {
    let a = map([('a', 'A'), ('b', 'B'), ('c', 'C')]);
    let b = map([('c', 'C'), ('d', 'D'), ('e', 'E')]);
    let c = a % b;
    assertEq(c.toString(), '{String("a"): String("A"), String("b"): String("B"), String("d"): String("D"), String("e"): String("E")}');
}