Advanced Collections

Tova provides specialized collection types in the collections namespace for common data structure patterns beyond arrays and objects.

OrderedDict

An insertion-ordered dictionary that maintains the order in which keys were added.

d = collections.OrderedDict()

Methods

set

d.set(key, value) -> OrderedDict

Sets a key-value pair. If the key exists, updates the value without changing order.

d = collections.OrderedDict()
d.set("b", 2)
d.set("a", 1)
d.set("c", 3)

get

d.get(key) -> T | Nil

Returns the value for a key, or nil if not found.

d.get("a")    // 1
d.get("z")    // nil

delete

d.delete(key) -> OrderedDict

Removes a key-value pair.

d.delete("b")

has

d.has(key) -> Bool

Returns true if the key exists.

d.has("a")    // true
d.has("z")    // false

keys / values / entries

d.keys() -> [String]
d.values() -> [T]
d.entries() -> [[String, T]]

Returns keys, values, or entries in insertion order.

d.keys()       // ["b", "a", "c"]
d.values()     // [2, 1, 3]
d.entries()    // [["b", 2], ["a", 1], ["c", 3]]

length

d.length -> Int

The number of entries.

---

DefaultDict

A dictionary that returns a default value for missing keys, generated by a factory function.

d = collections.DefaultDict(fn() 0)

Constructor

collections.DefaultDict(factory) -> DefaultDict

The factory is a function that produces the default value when a missing key is accessed.

// Counter pattern
counter = collections.DefaultDict(fn() 0)

// List accumulator pattern
groups = collections.DefaultDict(fn() [])

Methods

get

d.get(key) -> T

Returns the value for a key. If the key does not exist, calls the factory, stores the result, and returns it.

counter = collections.DefaultDict(fn() 0)
counter.get("apples")     // 0 (created by factory)
counter.set("apples", counter.get("apples") + 1)
counter.get("apples")     // 1

set

d.set(key, value) -> DefaultDict

Sets a key-value pair.

delete

d.delete(key) -> DefaultDict

Removes a key-value pair.

has

d.has(key) -> Bool

Returns true if the key exists (without triggering the factory).

---

Counter

A specialized collection for counting occurrences of items.

c = collections.Counter()

Methods

count

c.count(item) -> Counter

Increments the count for an item.

c = collections.Counter()
c.count("apple")
c.count("banana")
c.count("apple")

total

c.total() -> Int

Returns the sum of all counts.

c.total()    // 3

most_common

c.most_common(n?) -> [[T, Int]]

Returns the n most common items and their counts, sorted by frequency. If n is omitted, returns all items.

c.most_common()     // [["apple", 2], ["banana", 1]]
c.most_common(1)    // [["apple", 2]]

keys / values / entries

c.keys() -> [T]
c.values() -> [Int]
c.entries() -> [[T, Int]]

Returns items, counts, or item-count pairs.

---

Deque

A double-ended queue supporting efficient insertion and removal at both ends.

dq = collections.Deque()

Methods

push_back / push_front

dq.push_back(value) -> Deque
dq.push_front(value) -> Deque

Adds a value to the back or front.

dq = collections.Deque()
dq.push_back(1)
dq.push_back(2)
dq.push_front(0)
// [0, 1, 2]

pop_back / pop_front

dq.pop_back() -> T | Nil
dq.pop_front() -> T | Nil

Removes and returns the value at the back or front. Returns nil if empty.

dq.pop_front()    // 0
dq.pop_back()     // 2

peek_back / peek_front

dq.peek_back() -> T | Nil
dq.peek_front() -> T | Nil

Returns the value at the back or front without removing it.

length

dq.length -> Int

The number of elements.

toArray

dq.toArray() -> [T]

Converts the deque to an array.

dq = collections.Deque()
dq.push_back(1)
dq.push_back(2)
dq.push_back(3)
dq.toArray()    // [1, 2, 3]

---

Examples

Word Frequency Counter

text = "the cat sat on the mat the cat"
counter = collections.Counter()
for word in words(text) {
  counter.count(word)
}
counter.most_common(3)
// [["the", 3], ["cat", 2], ["sat", 1]]

Task Queue with Deque

queue = collections.Deque()
queue.push_back("task1")
queue.push_back("task2")
queue.push_front("urgent-task")

loop {
  task = queue.pop_front()
  if task == nil { break }
  process(task)
}

Grouping with DefaultDict

groups = collections.DefaultDict(fn() [])
for user in users {
  items = groups.get(user.role)
  groups.set(user.role, [...items, user])
}