API documentation

1 files changed, 215 insertions, 0 deletions

diff --git a/api/tables.md b/api/tables.md
new file mode 100644
index 00000000..bdf1ef15
--- /dev/null
+++ b/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}
+```