1 % API
   2 
   3 # Builtins
   4 
   5 # Table
   6 ## Table.clear
   7 
   8 ```tomo
   9 Table.clear : func(t: &{K:V} -> Void)
  10 ```
  11 
  12 Removes all key-value pairs from the table.
  13 
  14 Argument | Type | Description | Default
  15 ---------|------|-------------|---------
  16 t | `&{K:V}` | The reference to the table.  | -
  17 
  18 **Return:** Nothing.
  19 
  20 
  21 **Example:**
  22 ```tomo
  23 t := &{"A":1}
  24 t.clear()
  25 assert t[] == {}
  26 
  27 ```
  28 ## Table.difference
  29 
  30 ```tomo
  31 Table.difference : func(t: {K:V}, other: {K:V} -> {K:V})
  32 ```
  33 
  34 Return a table whose key/value pairs correspond to keys only present in one table, but not the other.
  35 
  36 Argument | Type | Description | Default
  37 ---------|------|-------------|---------
  38 t | `{K:V}` | The base table.  | -
  39 other | `{K:V}` | The other table.  | -
  40 
  41 **Return:** A table containing the common key/value pairs whose keys only appear in one table.
  42 
  43 
  44 **Example:**
  45 ```tomo
  46 t1 := {"A": 1, "B": 2, "C": 3}
  47 t2 := {"B": 2, "C":30, "D": 40}
  48 assert t1.difference(t2) == {"A": 1, "D": 40}
  49 
  50 ```
  51 ## Table.get
  52 
  53 ```tomo
  54 Table.get : func(t: {K:V}, key: K -> V?)
  55 ```
  56 
  57 Retrieves the value associated with a key, or returns `none` if the key is not present.
  58 
  59 Default values for the table are ignored.
  60 
  61 Argument | Type | Description | Default
  62 ---------|------|-------------|---------
  63 t | `{K:V}` | The table.  | -
  64 key | `K` | The key whose associated value is to be retrieved.  | -
  65 
  66 **Return:** The value associated with the key or `none` if the key is not found.
  67 
  68 
  69 **Example:**
  70 ```tomo
  71 t := {"A": 1, "B": 2}
  72 assert t.get("A") == 1
  73 assert t.get("????") == none
  74 assert t.get("A")! == 1
  75 assert t.get("????") or 0 == 0
  76 
  77 ```
  78 ## Table.get_or_set
  79 
  80 ```tomo
  81 Table.get_or_set : func(t: &{K:V}, key: K, default: V -> V?)
  82 ```
  83 
  84 If the given key is in the table, return the associated value. Otherwise, insert the given default value into the table and return it.
  85 
  86 If no default value is provided explicitly, but the table has a default value associated with it, the table's default value will be used.
  87 The default value is only evaluated if the key is missing.
  88 
  89 Argument | Type | Description | Default
  90 ---------|------|-------------|---------
  91 t | `&{K:V}` | The table.  | -
  92 key | `K` | The key whose associated value is to be retrieved.  | -
  93 default | `V` | The default value to insert and return if the key is not present in the table.  | -
  94 
  95 **Return:** Either the value associated with the key (if present) or the default value. The table will be mutated if the key is not already present.
  96 
  97 
  98 **Example:**
  99 ```tomo
 100 t := &{"A": @[1, 2, 3]; default=@[]}
 101 t.get_or_set("A").insert(4)
 102 t.get_or_set("B").insert(99)
 103 assert t["A"][] == [1, 2, 3, 4]
 104 assert t["B"][] == [99]
 105 assert t.get_or_set("C", @[0, 0, 0])[] == [0, 0, 0]
 106 
 107 ```
 108 ## Table.has
 109 
 110 ```tomo
 111 Table.has : func(t: {K:V}, key: K -> Bool)
 112 ```
 113 
 114 Checks if the table contains a specified key.
 115 
 116 Argument | Type | Description | Default
 117 ---------|------|-------------|---------
 118 t | `{K:V}` | The table.  | -
 119 key | `K` | The key to check for presence.  | -
 120 
 121 **Return:** `yes` if the key is present, `no` otherwise.
 122 
 123 
 124 **Example:**
 125 ```tomo
 126 assert {"A": 1, "B": 2}.has("A") == yes
 127 assert {"A": 1, "B": 2}.has("xxx") == no
 128 
 129 ```
 130 ## Table.intersection
 131 
 132 ```tomo
 133 Table.intersection : func(t: {K:V}, other: {K:V} -> {K:V})
 134 ```
 135 
 136 Return a table with only the matching key/value pairs that are common to both tables.
 137 
 138 Argument | Type | Description | Default
 139 ---------|------|-------------|---------
 140 t | `{K:V}` | The base table.  | -
 141 other | `{K:V}` | The other table.  | -
 142 
 143 **Return:** A table containing the common key/value pairs shared between two tables.
 144 
 145 
 146 **Example:**
 147 ```tomo
 148 t1 := {"A": 1, "B": 2, "C": 3}
 149 t2 := {"B": 2, "C":30, "D": 40}
 150 assert t1.intersection(t2) == {"B": 2}
 151 
 152 ```
 153 ## Table.remove
 154 
 155 ```tomo
 156 Table.remove : func(t: {K:V}, key: K -> Void)
 157 ```
 158 
 159 Removes the key-value pair associated with a specified key.
 160 
 161 Argument | Type | Description | Default
 162 ---------|------|-------------|---------
 163 t | `{K:V}` | The reference to the table.  | -
 164 key | `K` | The key of the key-value pair to remove.  | -
 165 
 166 **Return:** Nothing.
 167 
 168 
 169 **Example:**
 170 ```tomo
 171 t := &{"A": 1, "B": 2}
 172 t.remove("A")
 173 assert t == {"B": 2}
 174 
 175 ```
 176 ## Table.set
 177 
 178 ```tomo
 179 Table.set : func(t: {K:V}, key: K, value: V -> Void)
 180 ```
 181 
 182 Sets or updates the value associated with a specified key.
 183 
 184 Argument | Type | Description | Default
 185 ---------|------|-------------|---------
 186 t | `{K:V}` | The reference to the table.  | -
 187 key | `K` | The key to set or update.  | -
 188 value | `V` | The value to associate with the key.  | -
 189 
 190 **Return:** Nothing.
 191 
 192 
 193 **Example:**
 194 ```tomo
 195 t := &{"A": 1, "B": 2}
 196 t.set("C", 3)
 197 assert t == {"A": 1, "B": 2, "C": 3}
 198 
 199 ```
 200 ## Table.with
 201 
 202 ```tomo
 203 Table.with : func(t: {K:V}, other: {K:V} -> {K:V})
 204 ```
 205 
 206 Return a copy of a table with values added from another table
 207 
 208 Argument | Type | Description | Default
 209 ---------|------|-------------|---------
 210 t | `{K:V}` | The base table.  | -
 211 other | `{K:V}` | The other table from which new key/value pairs will be added.  | -
 212 
 213 **Return:** The original table, but with values from the other table added.
 214 
 215 
 216 **Example:**
 217 ```tomo
 218 t := {"A": 1, "B": 2}
 219 assert t.with({"B": 20, "C": 30}) == {"A": 1, "B": 20, "C": 30}
 220 
 221 ```
 222 ## Table.with_fallback
 223 
 224 ```tomo
 225 Table.with_fallback : func(t: {K:V}, fallback: {K:V}? -> {K:V})
 226 ```
 227 
 228 Return a copy of a table with a different fallback table.
 229 
 230 Argument | Type | Description | Default
 231 ---------|------|-------------|---------
 232 t | `{K:V}` | The table whose fallback will be replaced.  | -
 233 fallback | `{K:V}?` | The new fallback table value.  | -
 234 
 235 **Return:** The original table with a different fallback.
 236 
 237 
 238 **Example:**
 239 ```tomo
 240 t := {"A": 1; fallback={"B": 2}}
 241 t2 := t.with_fallback({"B": 3})
 242 assert t2["B"] == 3
 243 t3 := t.with_fallback(none)
 244 assert t3["B"] == none
 245 
 246 ```
 247 ## Table.without
 248 
 249 ```tomo
 250 Table.without : func(t: {K:V}, other: {K:V} -> {K:V})
 251 ```
 252 
 253 Return a copy of a table, but without any of the exact key/value pairs found in the other table.
 254 
 255 Only exact key/value pairs will be discarded. Keys with a non-matching value will be kept.
 256 
 257 Argument | Type | Description | Default
 258 ---------|------|-------------|---------
 259 t | `{K:V}` | The base table.  | -
 260 other | `{K:V}` | The other table whose key/value pairs will be omitted.  | -
 261 
 262 **Return:** The original table, but without the key/value pairs from the other table.
 263 
 264 
 265 **Example:**
 266 ```tomo
 267 t := {"A": 1, "B": 2, "C": 3}
 268 assert t.without({"B": 2, "C": 30, "D": 40}) == {"A": 1, "C": 3}
 269 
 270 ```