Collections Domain

The Collections domain is your toolbox for structured data. While List is great for simple sequences, real-world software needs more. Whether you need to look up users by their ID (Map), keep a list of unique tags (Set), or process tasks by priority (Heap), this domain provides persistent data structures designed for functional code.

Overview

use aivi.collections (Map, Set)

scores = Map.empty()
  |> Map.insert("Alice", 100)
  |> Map.insert("Bob", 95)

if scores |> Map.has("Alice") {
  print("Alice is present")
}

v1.0 Scope

• Map/Dict: persistent ordered maps (AVL/Red-Black) and/or HashMaps (HAMT).
• Set: persistent sets corresponding to map types.
• Queue/Deque: efficient FIFO/LIFO structures.
• Heap/PriorityQueue.

Literals and Merging (v1.0)

Collections introduce sigil-based literals for concise construction. These are domain literals and are validated at compile time.

Map literal

users = ~map{
  "id-1" => { name: "Alice", age: 30 }
  "id-2" => { name: "Bob", age: 25 }
}

Rules:

• Entries use key => value.
• Keys and values are full expressions.
• ...expr spreads another map into the literal.
• When duplicate keys exist, the last entry wins (right-biased).

defaults = ~map{ "theme" => "light", "lang" => "en" }
settings = ~map{ ...defaults, "theme" => "dark" }

Set literal

primes = ~set[2, 3, 5, 7, 11]
combined = ~set[...a, ...b]

Rules:

• Elements are expressions.
• ...expr spreads another set.
• Duplicates are removed (set semantics).

Merge operator

The Collections domain provides ++ as a right-biased merge for Map and union for Set.

use aivi.collections (Map, Set, domain Collections)

merged = map1 ++ map2
allTags = set1 ++ set2

Core API (v1.0)

The following functions are required for v1.0 implementations. Exact module layout may vary, but names and behavior should match.

Map

Function	Explanation
Map.empty Map k v	Creates an empty map.
Map.size map Map k v -> Int	Returns the number of entries.
Map.has key map k -> Map k v -> Bool	Returns whether key is present.
Map.get key map k -> Map k v -> Option v	Returns Some value or None.
Map.insert key value map k -> v -> Map k v -> Map k v	Returns a new map with the entry inserted.
Map.update key f map k -> (v -> v) -> Map k v -> Map k v	Applies f when key exists; otherwise no-op.
Map.remove key map k -> Map k v -> Map k v	Returns a new map without key.
Map.map f map (v -> v2) -> Map k v -> Map k v2	Transforms all values with f.
Map.mapWithKey f map (k -> v -> v2) -> Map k v -> Map k v2	Transforms values with access to keys.
Map.keys map Map k v -> List k	Returns all keys as a list.
Map.values map Map k v -> List v	Returns all values as a list.
Map.entries map Map k v -> List (k, v)	Returns all entries as key/value pairs.
Map.fromList entries List (k, v) -> Map k v	Builds a map from key/value pairs.
Map.toList map Map k v -> List (k, v)	Converts a map into key/value pairs.
Map.union left right Map k v -> Map k v -> Map k v	Merges maps with right-biased keys.

Notes:

• Map.union is right-biased (keys from the right map override).
• Map.update applies only when the key exists; otherwise it is a no-op.

Set

Function	Explanation
Set.empty Set a	Creates an empty set.
Set.size set Set a -> Int	Returns the number of elements.
Set.has value set a -> Set a -> Bool	Returns whether value is present.
Set.insert value set a -> Set a -> Set a	Returns a new set with value inserted.
Set.remove value set a -> Set a -> Set a	Returns a new set without value.
Set.union left right Set a -> Set a -> Set a	Returns the union of two sets.
Set.intersection left right Set a -> Set a -> Set a	Returns elements common to both sets.
Set.difference left right Set a -> Set a -> Set a	Returns elements in left not in right.
Set.fromList values List a -> Set a	Builds a set from a list.
Set.toList set Set a -> List a	Converts a set into a list.

Queue / Deque

Function	Explanation
Queue.empty Queue a	Creates an empty queue.
Queue.enqueue value queue a -> Queue a -> Queue a	Adds value to the back.
Queue.dequeue queue Queue a -> Option (a, Queue a)	Removes and returns the front value and remaining queue.
Queue.peek queue Queue a -> Option a	Returns the front value without removing it.
Deque.empty Deque a	Creates an empty deque.
Deque.pushFront value deque a -> Deque a -> Deque a	Adds value to the front.
Deque.pushBack value deque a -> Deque a -> Deque a	Adds value to the back.
Deque.popFront deque Deque a -> Option (a, Deque a)	Removes and returns the front value and rest.
Deque.popBack deque Deque a -> Option (a, Deque a)	Removes and returns the back value and rest.
Deque.peekFront deque Deque a -> Option a	Returns the front value without removing it.
Deque.peekBack deque Deque a -> Option a	Returns the back value without removing it.

Heap / PriorityQueue

Function	Explanation
Heap.empty Heap a	Creates an empty heap.
Heap.push value heap a -> Heap a -> Heap a	Inserts value into the heap.
Heap.popMin heap Heap a -> Option (a, Heap a)	Removes and returns the smallest value and remaining heap.
Heap.peekMin heap Heap a -> Option a	Returns the smallest value without removing it.

Heap ordering is determined by Ord for the element type.