Collections

Long and Double are supported collection values and hash keys. Double NaN keys are rejected and positive/negative zero are one key. See Long and Double.

Extended mode provides five typed heap collections: List, Map, Set, Queue, and Stack. A collection declaration states its element type explicitly and New takes the exact type from that declaration.

scores:Int List = New List
textures:Int Map By Str = New Map
selected:Entity Set = New Set
events:GameEvent Queue = New Queue
undo:EditCommand Stack = New Stack

The five collection words name a collection only there: directly after a value type, and directly after New. Anywhere else they are ordinary names, so a game can keep a map variable, a Set method or a Type Stack of its own. When a program has its own Type called Map, New Map makes a built-in Map wherever a Map is wanted, and an object of that Type everywhere else.

Type Map
    Field width, height
End Type

level:Map = New Map
names:Str Map By Int = New Map

List, Queue, and Stack accept Int, Float, Str, concrete-Type, and Interface values. Map values accept the same types. Map keys and Set values accept Int, Str, concrete-Type, and Interface values; Float is not hashable. Qualified Enum members are Int constants and can be stored in Int collections.

List

list.Add(value)
list.Remove(value)
list.RemoveAt(index)
list.Contains(value)
list.Count()
list.Clear()
value = list[index]
list[index] = value

A List is a contiguous, growable, zero-based sequence. It preserves insertion order and duplicates. Removing an item preserves the order of survivors.

Map

map[key] = value
value = map[key]
map.ContainsKey(key)
map.Remove(key)
map.GetOrDefault(key, fallback)
map.Count()
map.Clear()

Map keys are unique. Assigning an existing key replaces its value. Reading a missing indexed key is a runtime error; GetOrDefault performs a non-failing lookup. String keys use case-sensitive content equality. Object and Interface keys use object identity.

Set

added = set.Add(value)
set.Remove(value)
set.Contains(value)
set.Count()
set.Clear()

A Set stores each value once. Add returns True only for a new value.

Queue and Stack

queue.Enqueue(value)
value = queue.Dequeue()
value = queue.Peek()

stack.Push(value)
value = stack.Pop()
value = stack.Peek()

Queue is first-in, first-out. Stack is last-in, first-out. Peek does not remove the value. Peek, Dequeue, and Pop report a runtime error when empty. Both types also provide Count and Clear.

Each

For score:Int = Each scores
    total = total + score
Next

For name:Str = Each textures
    Print textures[name]
Next

List, Queue, Stack, and Set iterate values. Map iterates keys. Queue visits FIFO order and Stack visits newest to oldest. Map and Set order is unspecified. Queue, Stack, Map, and Set reject mutation during Each; List retains its documented mutation-safe traversal behavior.

References and cleanup

Collection assignment creates an alias to the same container. Collections own copies of stored Strings and retain stored objects, but removing an object never calls Delete on it. Use Delete collection when finished. Delete invalidates all aliases and releases stored references. Null elements, keys, and object values are rejected.

Collection types are invariant and cannot be nested or placed inside arrays. See the compilable collections example and the Multidimensional Arrays reference for Extended fixed-size square-bracket arrays.