API documentation

api/arrays.md

@@ -0,0 +1,669 @@
+# Arrays
+
+Tomo supports arrays as a container type that holds a list of elements of any
+type in a compact format. Arrays are immutable by default, but use
+copy-on-write semantics to efficiently mutate in place when possible. **Arrays
+are 1-indexed**, which means the first item in the array has index `1`.
+
+```tomo
+nums := [10, 20, 30]
+```
+
+## Array Methods
+
+### `binary_search`
+
+**Description:**  
+Performs a binary search on a sorted array.
+
+**Usage:**  
+```markdown
+binary_search(arr: [T], by=T.compare) -> Int
+```
+
+**Parameters:**
+
+- `arr`: The sorted array to search.
+- `by`: The comparison function used to determine order. If not specified, the
+  default comparison function for the item type will be used.
+
+**Returns:**  
+Assuming the input array is sorted according to the given comparison function,
+return the index where the given item would be inserted to maintain the sorted
+order.
+
+**Example:**  
+```markdown
+>> [1, 3, 5, 7, 9]:binary_search(5)
+= 3
+
+>> [1, 3, 5, 7, 9]:binary_search(-999)
+= 1
+
+>> [1, 3, 5, 7, 9]:binary_search(999)
+= 6
+```
+
+---
+
+### `by`
+
+**Description:**  
+Creates a new array with elements spaced by the specified step value.
+
+**Usage:**  
+```markdown
+by(arr: [T], step: Int) -> [T]
+```
+
+**Parameters:**
+
+- `arr`: The original array.
+- `step`: The step value for selecting elements.
+
+**Returns:**  
+A new array with every `step`-th element from the original array.
+
+**Example:**  
+```markdown
+>> [1, 2, 3, 4, 5, 6]:by(2)
+= [1, 3, 5]
+```
+
+---
+
+### `clear`
+
+**Description:**  
+Clears all elements from the array.
+
+**Usage:**  
+```markdown
+clear(arr: & [T]) -> Void
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the array to be cleared.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> my_array:clear()
+```
+
+---
+
+### `counts`
+
+**Description:**  
+Counts the occurrences of each element in the array.
+
+**Usage:**  
+```markdown
+counts(arr: [T]) -> {T: Int}
+```
+
+**Parameters:**
+
+- `arr`: The array to count elements in.
+
+**Returns:**  
+A table mapping each element to its count.
+
+**Example:**  
+```markdown
+>> [10, 20, 30, 30, 30]:counts()
+= {10: 1, 20: 1, 30: 3}
+```
+
+---
+
+### `find`
+
+**Description:**  
+Finds the index of the first occurrence of an element.
+
+**Usage:**  
+```markdown
+find(arr: [T]) -> Int
+```
+
+**Parameters:**
+
+- `arr`: The array to search through.
+
+**Returns:**  
+The index of the first occurrence or `-1` if not found.
+
+**Example:**  
+```markdown
+>> [10, 20, 30, 40, 50]:find(20)
+= 2
+
+>> [10, 20, 30, 40, 50]:find(9999)
+= -1
+```
+
+---
+
+### `from`
+
+**Description:**  
+Returns a slice of the array starting from a specified index.
+
+**Usage:**  
+```markdown
+from(arr: [T], first: Int) -> [T]
+```
+
+**Parameters:**
+
+- `arr`: The original array.
+- `first`: The index to start from.
+
+**Returns:**  
+A new array starting from the specified index.
+
+**Example:**  
+```markdown
+>> [10, 20, 30, 40, 50]:from(3)
+= [30, 40, 50]
+```
+
+---
+
+### `has`
+
+**Description:**  
+Checks if the array has any elements.
+
+**Usage:**  
+```markdown
+has(arr: [T]) -> Bool
+```
+
+**Parameters:**
+
+- `arr`: The array to check.
+
+**Returns:**  
+`yes` if the array has elements, `no` otherwise.
+
+**Example:**  
+```markdown
+>> [10, 20, 30]:has(20)
+= yes
+```
+
+---
+
+### `heap_pop`
+
+**Description:**  
+Removes and returns the top element of a heap. By default, this is the
+*minimum* value in the heap.
+
+**Usage:**  
+```markdown
+heap_pop(arr: & [T], by=T.compare) -> T
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the heap.
+- `by`: The comparison function used to determine order. If not specified, the
+  default comparison function for the item type will be used.
+
+**Returns:**  
+The removed top element of the heap.
+
+**Example:**  
+```markdown
+>> my_heap := [30, 10, 20]
+>> my_heap:heapify()
+>> my_heap:heap_pop()
+= 10
+```
+
+---
+
+### `heap_push`
+
+**Description:**  
+Adds an element to the heap and maintains the heap property. By default, this
+is a *minimum* heap.
+
+**Usage:**  
+```markdown
+heap_push(arr: & [T], item: T, by=T.compare) -> Void
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the heap.
+- `item`: The item to be added.
+- `by`: The comparison function used to determine order. If not specified, the
+  default comparison function for the item type will be used.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> my_heap:heap_push(10)
+```
+
+---
+
+### `heapify`
+
+**Description:**  
+Converts an array into a heap.
+
+**Usage:**  
+```markdown
+heapify(arr: & [T], by=T.compare) -> Void
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the array to be heapified.
+- `by`: The comparison function used to determine order. If not specified, the
+  default comparison function for the item type will be used.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> my_heap := [30, 10, 20]
+>> my_heap:heapify()
+```
+
+---
+
+### `insert`
+
+**Description:**  
+Inserts an element at a specified position in the array.
+
+**Usage:**  
+```markdown
+insert(arr: & [T], item: T, at: Int = 0) -> Void
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the array.
+- `item`: The item to be inserted.
+- `at`: The index at which to insert the item (default is `0`). Since indices
+  are 1-indexed and negative indices mean "starting from the back", an index of
+  `0` means "after the last item".
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> arr := [10, 20]
+>> arr:insert(30)
+>> arr
+= [10, 20, 30]
+
+>> arr:insert(999, at=2)
+>> arr
+= [10, 999, 20, 30]
+```
+
+---
+
+### `insert_all`
+
+**Description:**  
+Inserts an array of items at a specified position in the array.
+
+**Usage:**  
+```markdown
+insert_all(arr: & [T], items: [T], at: Int = 0) -> Void
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the array.
+- `items`: The items to be inserted.
+- `at`: The index at which to insert the item (default is `0`). Since indices
+  are 1-indexed and negative indices mean "starting from the back", an index of
+  `0` means "after the last item".
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+arr := [10, 20]
+arr:insert_all([30, 40])
+>> arr
+= [10, 20, 30, 40]
+
+arr:insert_all([99, 100], at=2)
+>> arr
+= [10, 99, 100, 20, 30, 40]
+```
+
+---
+
+### `random`
+
+**Description:**  
+Selects a random element from the array.
+
+**Usage:**  
+```markdown
+random(arr: [T]) -> T
+```
+
+**Parameters:**
+
+- `arr`: The array from which to select a random element.
+
+**Returns:**  
+A random element from the array.
+
+**Example:**  
+```markdown
+>> [10, 20, 30]:random()
+= 20
+```
+
+---
+
+### `remove_at`
+
+**Description:**  
+Removes elements from the array starting at a specified index.
+
+**Usage:**  
+```markdown
+remove_at(arr: & [T], at: Int = -1, count: Int = 1) -> Void
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the array.
+- `at`: The index at which to start removing elements (default is `-1`, which means the end of the array).
+- `count`: The number of elements to remove (default is `1`).
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+arr := [10, 20, 30, 40, 50]
+arr:remove_at(2)
+>> arr
+= [10, 30, 40, 50]
+
+arr:remove_at(2, count=2)
+>> arr
+= [10, 50]
+```
+
+---
+
+### `remove_item`
+
+**Description:**  
+Removes all occurrences of a specified item from the array.
+
+**Usage:**  
+```markdown
+remove_item(arr: & [T], item: T, max_count: Int = -1) -> Void
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the array.
+- `item`: The item to be removed.
+- `max_count`: The maximum number of occurrences to remove (default is `-1`, meaning all occurrences).
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+arr := [10, 20, 10, 20, 30]
+arr:remove_item(10)
+>> arr
+= [20, 20, 30]
+
+arr:remove_item(20, max_count=1)
+>> arr
+= [20, 30]
+```
+
+---
+
+### `reversed`
+
+**Description:**  
+Returns a reversed slice of the array.
+
+**Usage:**  
+```markdown
+reversed(arr: [T]) -> [T]
+```
+
+**Parameters:**
+
+- `arr`: The array to be reversed.
+
+**Returns:**  
+A slice of the array with elements in reverse order.
+
+**Example:**  
+```markdown
+>> [10, 20, 30]:reversed()
+= [30, 20, 10]
+```
+
+---
+
+### `sample`
+
+**Description:**  
+Selects a sample of elements from the array, optionally with weighted
+probabilities.
+
+**Usage:**  
+```markdown
+sample(arr: [T], count: Int, weights: [Num]) -> [T]
+```
+
+**Parameters:**
+
+- `arr`: The array to sample from.
+- `count`: The number of elements to sample.
+- `weights`: The probability weights for each element in the array. These
+  values do not need to add up to any particular number, they are relative
+  weights. If no weights are provided, the default is equal probabilities.
+  Negative, infinite, or NaN weights will cause a runtime error. If the number of
+  weights given is less than the length of the array, elements from the rest of
+  the array are considered to have zero weight.
+
+**Returns:**  
+A list of sampled elements from the array.
+
+**Example:**  
+```markdown
+>> [10, 20, 30]:sample(2, weights=[90%, 5%, 5%])
+= [10, 10]
+```
+
+---
+
+### `shuffle`
+
+**Description:**  
+Shuffles the elements of the array in place.
+
+**Usage:**  
+```markdown
+shuffle(arr: & [T]) -> Void
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the array to be shuffled.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> arr:shuffle()
+```
+
+---
+
+### `shuffled`
+
+**Description:**  
+Creates a new array with elements shuffled.
+
+**Usage:**  
+```markdown
+shuffled(arr: [T]) -> [T]
+```
+
+**Parameters:**
+
+- `arr`: The array to be shuffled.
+
+**Returns:**  
+A new array with shuffled elements.
+
+**Example:**  
+```markdown
+>> [10, 20, 30, 40]:shuffled()
+= [40, 10, 30, 20]
+```
+
+---
+
+### `sort`
+
+**Description:**  
+Sorts the elements of the array in place in ascending order (small to large).
+
+**Usage:**  
+```markdown
+sort(arr: & [T], by=T.compare) -> Void
+```
+
+**Parameters:**
+
+- `arr`: The mutable reference to the array to be sorted.
+- `by`: The comparison function used to determine order. If not specified, the
+  default comparison function for the item type will be used.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+arr := [40, 10, -30, 20]
+arr:sort()
+>> arr
+= [-30, 10, 20, 40]
+
+arr:sort(func(a,b:&Int): a:abs() <> b:abs())
+>> arr
+= [10, 20, -30, 40]
+```
+
+---
+
+### `sorted`
+
+**Description:**  
+Creates a new array with elements sorted.
+
+**Usage:**  
+```markdown
+sorted(arr: [T], by=T.compare) -> [T]
+```
+
+**Parameters:**
+
+- `arr`: The array to be sorted.
+- `by`: The comparison function used to determine order. If not specified, the
+  default comparison function for the item type will be used.
+
+**Returns:**  
+A new array with sorted elements.
+
+**Example:**  
+```markdown
+>> [40, 10, -30, 20]:sorted()
+= [-30, 10, 20, 40]
+
+>> [40, 10, -30, 20]:sorted(func(a,b:&Int): a:abs() <> b:abs())
+= [10, 20, -30, 40]
+```
+
+---
+
+### `to`
+
+**Description:**  
+Returns a slice of the array from the start of the original array up to a specified index (inclusive).
+
+**Usage:**  
+```markdown
+to(arr: [T], last: Int) -> [T]
+```
+
+**Parameters:**
+
+- `arr`: The original array.
+- `last`: The index up to which elements should be included.
+
+**Returns:**  
+A new array containing elements from the start up to the specified index.
+
+**Example:**  
+```markdown
+>> [10, 20, 30, 40, 50]:to(3)
+= [10, 20, 30]
+
+>> [10, 20, 30, 40, 50]:to(-2)
+= [10, 20, 30, 40]
+```
+
+---
+
+### `unique`
+
+**Description:**  
+Returns a Set that contains the unique elements of the array.
+
+**Usage:**  
+```markdown
+unique(arr: [T]) -> {T}
+```
+
+**Parameters:**
+
+- `arr`: The array to process.
+
+**Returns:**  
+A set containing only unique elements from the array.
+
+**Example:**  
+```markdown
+>> [10, 20, 10, 10, 30]:unique()
+= {10, 20, 30}
+```

api/channels.md

@@ -0,0 +1,138 @@
+# Channels
+
+Channels are a thread-safe message queue for communicating between threads,
+although they can also be used as a general-purpose queue.
+
+```tomo
+channel := |Int|
+channel:push(10)
+channel:push(20)
+>> channel:pop()
+= 10
+>> channel:pop()
+= 20
+```
+
+## Channel Methods
+
+### `push`
+
+**Description:**  
+Adds an item to the channel.
+
+**Usage:**  
+```markdown
+push(channel:|T|, item: T) -> Void
+```
+
+**Parameters:**
+
+- `channel`: The channel to which the item will be added.
+- `item`: The item to add to the channel.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> channel:push("Hello")
+```
+
+---
+
+### `push_all`
+
+**Description:**  
+Adds multiple items to the channel.
+
+**Usage:**  
+```markdown
+push_all(channel:|T|, items: [T]) -> Void
+```
+
+**Parameters:**
+
+- `channel`: The channel to which the items will be added.
+- `items`: The array of items to add to the channel.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> channel:push_all([1, 2, 3])
+```
+
+---
+
+### `pop`
+
+**Description:**  
+Removes and returns an item from the channel. If the channel is empty, it waits until an item is available.
+
+**Usage:**  
+```markdown
+pop(channel:|T|) -> T
+```
+
+**Parameters:**
+
+- `channel`: The channel from which to remove an item.
+
+**Returns:**  
+The item removed from the channel.
+
+**Example:**  
+```markdown
+>> channel:pop()
+= "Hello"
+```
+
+---
+
+### `clear`
+
+**Description:**  
+Removes all items from the channel.
+
+**Usage:**  
+```markdown
+clear(channel:|T|) -> Void
+```
+
+**Parameters:**
+
+- `channel`: The mutable reference to the channel.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> channel:clear()
+```
+
+---
+
+### `view`
+
+**Description:**  
+Returns a list of all items currently in the channel without removing them.
+
+**Usage:**  
+```markdown
+channel:view() -> [T]
+```
+
+**Parameters:**
+
+- `channel`: The channel to view.
+
+**Returns:**  
+An array of items currently in the channel.
+
+**Example:**  
+```markdown
+>> channel:view()
+= [1, 2, 3]
+```

api/ranges.md

@@ -0,0 +1,65 @@
+# Ranges
+
+Ranges are Tomo's way to do iteration over numeric ranges. Ranges are typically
+created using the `Int.to()` method like so: `5:to(10)`. Ranges are
+*inclusive*.
+
+```tomo
+>> [i for i in 3:to(5)]
+= [3, 4, 5]
+```
+
+---
+
+## Range Methods
+
+### `reversed`
+
+**Description:**  
+Returns a reversed copy of the range.
+
+**Usage:**  
+```tomo
+reversed(range: Range) -> Range
+```
+
+**Parameters:**
+
+- `range`: The range to be reversed.
+
+**Returns:**  
+A new `Range` with the order of elements reversed.
+
+**Example:**  
+```tomo
+>> 1:to(5):reversed()
+= Range(first=5, last=1, step=-1)
+```
+
+---
+
+### `by`
+
+**Description:**  
+Creates a new range with a specified step value.
+
+**Usage:**  
+```tomo
+by(range: Range, step: Int) -> Range
+```
+
+**Parameters:**
+
+- `range`: The original range.
+- `step`: The step value to be used in the new range.
+
+**Returns:**  
+A new `Range` that increments by the specified step value.
+
+**Example:**  
+```tomo
+>> 1:to(5):by(2)
+= Range(first=1, last=5, step=2)
+```
+
+---

api/sets.md

@@ -0,0 +1,297 @@
+# Sets
+
+Sets represent an unordered collection of unique elements. These are
+implemented using hash tables.
+
+```tomo
+a := {10, 20, 30}
+b := {20, 30}
+>> a:overlap(b)
+= {20}
+```
+
+Here’s the Markdown documentation for set functions:
+
+---
+
+## Set Functions
+
+### `has`
+
+**Description:**  
+Checks if the set contains a specified item.
+
+**Usage:**  
+```tomo
+has(set:{T}, item:T) -> Bool
+```
+
+**Parameters:**
+
+- `set`: The set to check.
+- `item`: The item to check for presence.
+
+**Returns:**  
+`yes` if the item is present, `no` otherwise.
+
+**Example:**  
+```tomo
+>> {10, 20}:has(20)
+= yes
+```
+
+---
+
+### `add`
+
+**Description:**  
+Adds an item to the set.
+
+**Usage:**  
+```tomo
+add(set:{T}, item: T) -> Void
+```
+
+**Parameters:**
+
+- `set`: The mutable reference to the set.
+- `item`: The item to add to the set.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> nums:add(42)
+```
+
+---
+
+### `add_all`
+
+**Description:**  
+Adds multiple items to the set.
+
+**Usage:**  
+```tomo
+add_all(set:&{T}, items: [T]) -> Void
+```
+
+**Parameters:**
+
+- `set`: The mutable reference to the set.
+- `items`: The array of items to add to the set.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> nums:add_all([1, 2, 3])
+```
+
+---
+
+### `remove`
+
+**Description:**  
+Removes an item from the set.
+
+**Usage:**  
+```tomo
+remove(set:&{T}, item: T) -> Void
+```
+
+**Parameters:**
+
+- `set`: The mutable reference to the set.
+- `item`: The item to remove from the set.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> nums:remove(42)
+```
+
+---
+
+### `remove_all`
+
+**Description:**  
+Removes multiple items from the set.
+
+**Usage:**  
+```tomo
+remove_all(set:&{T}, items: [T]) -> Void
+```
+
+**Parameters:**
+
+- `set`: The mutable reference to the set.
+- `items`: The array of items to remove from the set.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> nums:remove_all([1, 2, 3])
+```
+
+---
+
+### `clear`
+
+**Description:**  
+Removes all items from the set.
+
+**Usage:**  
+```tomo
+clear(set:&{T}) -> Void
+```
+
+**Parameters:**
+
+- `set`: The mutable reference to the set.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> nums:clear()
+```
+
+---
+
+### `with`
+
+**Description:**  
+Creates a new set that is the union of the original set and another set.
+
+**Usage:**  
+```tomo
+with(set:{T}, other: {T}) -> {T}
+```
+
+**Parameters:**
+
+- `set`: The original set.
+- `other`: The set to union with.
+
+**Returns:**  
+A new set containing all items from both sets.
+
+**Example:**  
+```tomo
+>> {1, 2}:with({2, 3})
+= {1, 2, 3}
+```
+
+---
+
+### `overlap`
+
+**Description:**  
+Creates a new set with items that are in both the original set and another set.
+
+**Usage:**  
+```tomo
+overlap(set:{T}, other: {T}) -> {T}
+```
+
+**Parameters:**
+
+- `set`: The original set.
+- `other`: The set to intersect with.
+
+**Returns:**  
+A new set containing only items present in both sets.
+
+**Example:**  
+```tomo
+>> {1, 2}:overlap({2, 3})
+= {2}
+```
+
+---
+
+### `without`
+
+**Description:**  
+Creates a new set with items from the original set but without items from another set.
+
+**Usage:**  
+```tomo
+without(set:{T}, other: {T}) -> {T}
+```
+
+**Parameters:**
+
+- `set`: The original set.
+- `other`: The set of items to remove from the original set.
+
+**Returns:**  
+A new set containing items from the original set excluding those in the other set.
+
+**Example:**  
+```tomo
+>> {1, 2}:without({2, 3})
+= {1}
+```
+
+---
+
+### `is_subset_of`
+
+**Description:**  
+Checks if the set is a subset of another set.
+
+**Usage:**  
+```tomo
+set:is_subset_of(other: {T}, strict: Bool = no) -> Bool
+```
+
+**Parameters:**
+
+- `set`: The set to check.
+- `other`: The set to compare against.
+- `strict`: If `yes`, checks if the set is a strict subset (does not equal the other set).
+
+**Returns:**  
+`yes` if the set is a subset of the other set (strictly or not), `no` otherwise.
+
+**Example:**  
+```tomo
+>> {1, 2}:is_subset_of({1, 2, 3})
+= yes
+```
+
+---
+
+### `is_superset_of`
+
+**Description:**  
+Checks if the set is a superset of another set.
+
+**Usage:**  
+```tomo
+is_superset_of(set:{T}, other: {T}, strict: Bool = no) -> Bool
+```
+
+**Parameters:**
+
+- `set`: The set to check.
+- `other`: The set to compare against.
+- `strict`: If `yes`, checks if the set is a strict superset (does not equal the other set).
+
+**Returns:**  
+`yes` if the set is a superset of the other set (strictly or not), `no` otherwise.
+
+**Example:**  
+```tomo
+>> {1, 2, 3}:is_superset_of({1, 2})
+= yes
+```

api/tables.md

@@ -0,0 +1,215 @@
+# Tables
+
+Tables are Tomo's associative mapping structure, also known as a Dictionary or
+Map. Tables are efficiently implemented as a hash table that preserves
+insertion order and has fast access to keys and values as array slices. Tables
+support *all* types as both keys and values.
+
+Tables do not support square bracket indexing (`t[key]`), but instead rely on
+the methods `:get(key)` and `:set(key, value)`. This is explicit to avoid
+hiding the fact that table lookups and table insertion are performing function
+calls and have edge conditions like a failure to find an entry.
+
+---
+
+## Table Methods
+
+### `bump`
+
+**Description:**  
+Increments the value associated with a key by a specified amount. If the key is
+not already in the table, its value will be assumed to be zero.
+
+**Usage:**  
+```markdown
+bump(t:{K:V}, key: K, amount: Int = 1) -> Void
+```
+
+**Parameters:**
+
+- `t`: The mutable reference to the table.
+- `key`: The key whose value is to be incremented.
+- `amount`: The amount to increment the value by (default: 1).
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> t := {"A":1}
+t:bump("A")
+t:bump("B", 10)
+>> t
+= {"A": 2, "B": 10}
+```
+
+---
+
+### `clear`
+
+**Description:**  
+Removes all key-value pairs from the table.
+
+**Usage:**  
+```markdown
+t:clear() -> Void
+```
+
+**Parameters:**
+
+- `t`: The mutable reference to the table.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> t:clear()
+```
+
+---
+
+### `get`
+
+**Description:**  
+Retrieves the value associated with a key, or returns a default value if the key is not present.
+
+**Usage:**  
+```markdown
+t:get(key: K, default: V) -> V
+```
+
+**Parameters:**
+
+- `t`: The table.
+- `key`: The key whose associated value is to be retrieved.
+- `default`: The value to return if the key is not present. If this argument is
+  not provided, a runtime error will be created if the key is not present.
+
+**Returns:**  
+The value associated with the key or the default value if the key is not found.
+
+**Example:**  
+```markdown
+>> t := {"A":1, "B":2}
+>> t:get("A")
+= 1
+
+>> t:get("xxx", 0)
+= 0
+```
+
+---
+
+### `get_or_null`
+
+**Description:**  
+Retrieves the value associated with a key, or returns `null` if the key is not present.
+This method is only available on tables whose values are pointers.
+
+**Usage:**  
+```markdown
+t:get_or_null(key: K) -> @V?
+```
+
+**Parameters:**
+
+- `t`: The table.
+- `key`: The key whose associated value is to be retrieved.
+
+**Returns:**  
+A mutable reference to the value associated with the key or `null` if the key is not found.
+
+**Example:**  
+```markdown
+>> t := {"A": @[10]}
+>> t:get_or_null("A")
+= @[10]?
+>> t:get_or_null("xxx")
+= !@[Int]
+```
+
+---
+
+### `has`
+
+**Description:**  
+Checks if the table contains a specified key.
+
+**Usage:**  
+```markdown
+has(t:{K:V}, key: K) -> Bool
+```
+
+**Parameters:**
+
+- `t`: The table.
+- `key`: The key to check for presence.
+
+**Returns:**  
+`yes` if the key is present, `no` otherwise.
+
+**Example:**  
+```markdown
+>> {"A":1, "B":2}:has("A")
+= yes
+>> {"A":1, "B":2}:has("xxx")
+= no
+```
+
+---
+
+### `remove`
+
+**Description:**  
+Removes the key-value pair associated with a specified key.
+
+**Usage:**  
+```markdown
+remove(t:{K:V}, key: K) -> Void
+```
+
+**Parameters:**
+
+- `t`: The mutable reference to the table.
+- `key`: The key of the key-value pair to remove.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+t := {"A":1, "B":2}
+t:remove("A")
+>> t
+= {"B": 2}
+```
+
+---
+
+### `set`
+
+**Description:**  
+Sets or updates the value associated with a specified key.
+
+**Usage:**  
+```markdown
+set(t:{K:V}, key: K, value: V) -> Void
+```
+
+**Parameters:**
+
+- `t`: The mutable reference to the table.
+- `key`: The key to set or update.
+- `value`: The value to associate with the key.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+t := {"A": 1, "B": 2}
+t:set("C", 3)
+>> t
+= {"A": 1, "B": 2, "C": 3}
+```

api/text.md

@@ -282,7 +282,7 @@ finding the value because the two texts are equivalent under normalization.
 Converts a `Text` value to a C-style string.
 
 **Usage:**  
-```markdown
+```tomo
 as_c_string(text: Text) -> CString
 ```
 
@@ -294,7 +294,7 @@ as_c_string(text: Text) -> CString
 A C-style string (`CString`) representing the text.
 
 **Example:**  
-```markdown
+```tomo
 >> "Hello":as_c_string()
 = CString("Hello")
 ```
@@ -307,7 +307,7 @@ A C-style string (`CString`) representing the text.
 Converts a `Text` value to an array of bytes.
 
 **Usage:**  
-```markdown
+```tomo
 bytes(text: Text) -> [Int8]
 ```
 
@@ -319,7 +319,7 @@ bytes(text: Text) -> [Int8]
 An array of bytes (`[Int8]`) representing the text.
 
 **Example:**  
-```markdown
+```tomo
 >> "Amélie":bytes()
 = [65_i8, 109_i8, 101_i8, -52_i8, -127_i8, 108_i8, 105_i8, 101_i8]
 ```
@@ -332,7 +332,7 @@ An array of bytes (`[Int8]`) representing the text.
 Returns a list of character names from the text.
 
 **Usage:**  
-```markdown
+```tomo
 character_names(text: Text) -> [Text]
 ```
 
@@ -344,7 +344,7 @@ character_names(text: Text) -> [Text]
 A list of character names (`[Text]`).
 
 **Example:**  
-```markdown
+```tomo
 >> "Amélie":character_names()
 = ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E", "COMBINING ACUTE ACCENT", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"]
 ```
@@ -360,7 +360,7 @@ in a text editor and you hit the left or right arrow key, it will move the
 cursor by one graphical cluster.
 
 **Usage:**  
-```markdown
+```tomo
 clusters(text: Text) -> [Text]
 ```
 
@@ -372,7 +372,7 @@ clusters(text: Text) -> [Text]
 A list of graphical clusters (`[Text]`) within the text.
 
 **Example:**  
-```markdown
+```tomo
 >> "Amélie":clusters()
 = ["A", "m", "é", "l", "i", "e"] : [Text]
 ```
@@ -385,7 +385,7 @@ A list of graphical clusters (`[Text]`) within the text.
 Returns a list of Unicode code points for the text.
 
 **Usage:**  
-```markdown
+```tomo
 codepoints(text: Text) -> [Int32]
 ```
 
@@ -397,7 +397,7 @@ codepoints(text: Text) -> [Int32]
 A list of Unicode code points (`[Int32]`).
 
 **Example:**  
-```markdown
+```tomo
 >> "Amélie":codepoints()
 = [65_i32, 109_i32, 101_i32, 769_i32, 108_i32, 105_i32, 101_i32] : [Int32]
 ```
@@ -410,7 +410,7 @@ A list of Unicode code points (`[Int32]`).
 Converts a C-style string to a `Text` value.
 
 **Usage:**  
-```markdown
+```tomo
 from_c_string(str: CString) -> Text
 ```
 
@@ -422,7 +422,7 @@ from_c_string(str: CString) -> Text
 A `Text` value representing the C-style string.
 
 **Example:**  
-```markdown
+```tomo
 from_c_string(CString("Hello"))  // "Hello"
 ```
 
@@ -434,7 +434,7 @@ from_c_string(CString("Hello"))  // "Hello"
 Checks if the `Text` contains a target substring.
 
 **Usage:**  
-```markdown
+```tomo
 has(text: Text, target: Text, where: Where = Where.Anywhere) -> Bool
 ```
 
@@ -448,7 +448,7 @@ has(text: Text, target: Text, where: Where = Where.Anywhere) -> Bool
 `yes` if the target substring is found, `no` otherwise.
 
 **Example:**  
-```markdown
+```tomo
 has("Hello, world!", "world")  // yes
 ```
 
@@ -460,7 +460,7 @@ has("Hello, world!", "world")  // yes
 Joins a list of text pieces with a specified glue.
 
 **Usage:**  
-```markdown
+```tomo
 join(glue: Text, pieces: [Text]) -> Text
 ```
 
@@ -473,7 +473,7 @@ join(glue: Text, pieces: [Text]) -> Text
 A single `Text` value with the pieces joined by the glue.
 
 **Example:**  
-```markdown
+```tomo
 join(", ", ["apple", "banana", "cherry"])  // "apple, banana, cherry"
 ```
 
@@ -485,7 +485,7 @@ join(", ", ["apple", "banana", "cherry"])  // "apple, banana, cherry"
 Converts all characters in the text to lowercase.
 
 **Usage:**  
-```markdown
+```tomo
 lower(text: Text) -> Text
 ```
 
@@ -497,7 +497,7 @@ lower(text: Text) -> Text
 The lowercase version of the text.
 
 **Example:**  
-```markdown
+```tomo
 lower("HELLO")  // "hello"
 ```
 
@@ -509,7 +509,7 @@ lower("HELLO")  // "hello"
 Returns the number of bytes used by the text.
 
 **Usage:**  
-```markdown
+```tomo
 num_bytes(text: Text) -> Int
 ```
 
@@ -521,7 +521,7 @@ num_bytes(text: Text) -> Int
 The number of bytes used by the text.
 
 **Example:**  
-```markdown
+```tomo
 num_bytes("Hello")  // 5
 ```
 
@@ -533,7 +533,7 @@ num_bytes("Hello")  // 5
 Returns the number of clusters in the text.
 
 **Usage:**  
-```markdown
+```tomo
 num_clusters(text: Text) -> Int
 ```
 
@@ -545,7 +545,7 @@ num_clusters(text: Text) -> Int
 The number of clusters in the text.
 
 **Example:**  
-```markdown
+```tomo
 num_clusters("Hello")  // 5
 ```
 
@@ -557,7 +557,7 @@ num_clusters("Hello")  // 5
 Returns the number of Unicode code points in the text.
 
 **Usage:**  
-```markdown
+```tomo
 num_codepoints(text: Text) -> Int
 ```
 
@@ -569,7 +569,7 @@ num_codepoints(text: Text) -> Int
 The number of Unicode code points in the text.
 
 **Example:**  
-```markdown
+```tomo
 num_codepoints("Hello")  // 5
 ```
 
@@ -581,7 +581,7 @@ num_codepoints("Hello")  // 5
 Formats the text as a quoted string.
 
 **Usage:**  
-```markdown
+```tomo
 quoted(text: Text, color: Bool = no) -> Text
 ```
 
@@ -594,7 +594,7 @@ quoted(text: Text, color: Bool = no) -> Text
 The text formatted as a quoted string.
 
 **Example:**  
-```markdown
+```tomo
 quoted("Hello")  // "\"Hello\""
 ```
 
@@ -606,7 +606,7 @@ quoted("Hello")  // "\"Hello\""
 Replaces occurrences of a pattern in the text with a replacement string.
 
 **Usage:**  
-```markdown
+```tomo
 replace(text: Text, pattern: Text, replacement: Text, limit: Int = -1) -> Text
 ```
 
@@ -621,7 +621,7 @@ replace(text: Text, pattern: Text, replacement: Text, limit: Int = -1) -> Text
 The text with occurrences of the pattern replaced.
 
 **Example:**  
-```markdown
+```tomo
 replace("Hello world", "world", "there")  // "Hello there"
 ```
 
@@ -633,7 +633,7 @@ replace("Hello world", "world", "there")  // "Hello there"
 Splits the text into a list of substrings based on a delimiter.
 
 **Usage:**  
-```markdown
+```tomo
 split(text: Text, split: Text) -> [Text]
 ```
 
@@ -646,7 +646,7 @@ split(text: Text, split: Text) -> [Text]
 A list of substrings resulting from the split.
 
 **Example:**  
-```markdown
+```tomo
 split("apple,banana,cherry", ",")  // ["apple", "banana", "cherry"]
 ```
 
@@ -658,7 +658,7 @@ split("apple,banana,cherry", ",")  // ["apple", "banana", "cherry"]
 Converts the text to title case (capitalizing the first letter of each word).
 
 **Usage:**  
-```markdown
+```tomo
 title(text: Text) -> Text
 ```
 
@@ -670,7 +670,7 @@ title(text: Text) -> Text
 The text in title case.
 
 **Example:**  
-```markdown
+```tomo
 title("hello world")  // "Hello World"
 ```
 
@@ -682,7 +682,7 @@ title("hello world")  // "Hello World"
 Trims characters from the beginning and end of the text.
 
 **Usage:**  
-```markdown
+```tomo
 trimmed(text: Text, trim: Text = " {\n\r\t}", where: Where = Where.Anywhere) -> Text
 ```
 
@@ -696,7 +696,7 @@ trimmed(text: Text, trim: Text = " {\n\r\t}", where: Where = Where.Anywhere) ->
 The trimmed text.
 
 **Example:**  
-```markdown
+```tomo
 trimmed("  Hello  ")  // "Hello"
 ```
 
@@ -708,7 +708,7 @@ trimmed("  Hello  ")  // "Hello"
 Converts all characters in the text to uppercase.
 
 **Usage:**  
-```markdown
+```tomo
 upper(text: Text) -> Text
 ```
 
@@ -720,7 +720,7 @@ upper(text: Text) -> Text
 The uppercase version of the text.
 
 **Example:**  
-```markdown
+```tomo
 upper("hello")  // "HELLO"
 ```
 
@@ -732,7 +732,7 @@ upper("hello")  // "HELLO"
 Removes all occurrences of a target substring from the text.
 
 **Usage:**  
-```markdown
+```tomo
 without(text: Text, target: Text, where: Where = Where.Anywhere) -> Text
 ```
 
@@ -746,7 +746,7 @@ without(text: Text, target: Text, where: Where = Where.Anywhere) -> Text
 The text with occurrences of the target removed.
 
 **Example:**  
-```markdown
+```tomo
 without("Hello world", "world")  // "Hello "
 ```
 

api/threads.md

@@ -0,0 +1,111 @@
+# Threads
+
+Tomo supports POSIX threads (pthreads) through the `Thread` type. The
+recommended practice is to have each thread interact with other threads only
+through thread-safe Channels with no other shared data.
+
+## Thread Methods
+
+### `new`
+
+**Description:**  
+Creates a new thread to execute a specified function.
+
+**Usage:**  
+```tomo
+Thread.new(fn: func() -> Void) -> Thread
+```
+
+**Parameters:**
+
+- `fn`: The function to be executed by the new thread.
+
+**Returns:**  
+A new `Thread` object representing the created thread.
+
+**Example:**  
+```tomo
+>> jobs := |Int|
+>> results := |Int|
+>> thread := Thread.new(func():
+    while yes:
+        input := jobs:pop()
+        results:push(input + 10
+)
+= Thread<0x12345678>
+>> jobs:push(10)
+>> results:pop()
+= 11
+```
+
+---
+
+### `cancel`
+
+**Description:**  
+Requests the cancellation of a specified thread.
+
+**Usage:**  
+```tomo
+cancel(thread: Thread) -> Void
+```
+
+**Parameters:**
+
+- `thread`: The thread to cancel.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> thread:cancel()
+```
+
+---
+
+### `join`
+
+**Description:**  
+Waits for a specified thread to terminate.
+
+**Usage:**  
+```tomo
+join(thread: Thread) -> Void
+```
+
+**Parameters:**
+
+- `thread`: The thread to join.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> thread:join()
+```
+
+---
+
+### `detach`
+
+**Description:**  
+Detaches a specified thread, allowing it to run independently.
+
+**Usage:**  
+```tomo
+detach(thread: Thread) -> Void
+```
+
+**Parameters:**
+
+- `thread`: The thread to detach.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> thread:detach()
+```