1 # Tables
   2 
   3 Tables are Tomo's associative mapping structure, also known as a Dictionary or
   4 Map. Tables are efficiently implemented as a hash table that preserves
   5 insertion order and has fast access to keys and values as list slices. Tables
   6 support *all* types as both keys and values.
   7 
   8 ## Syntax
   9 
  10 Tables are written using `{}` curly braces with `:` colons associating key
  11 expressions with value expressions and commas between entries:
  12 
  13 ```tomo
  14 table := {"A": 10, "B": 20}
  15 ```
  16 
  17 Empty tables must specify the key and value types explicitly:
  18 
  19 ```tomo
  20 empty : {Text:Int} = {}
  21 ```
  22 
  23 For type annotations, a table that maps keys with type `K` to values of type
  24 `V` is written as `{K:V}`.
  25 
  26 ### Comprehensions
  27 
  28 Similar to lists, tables can use comprehensions to dynamically construct tables:
  29 
  30 ```tomo
  31 t := {i: 10*i for i in 10}
  32 t := {i: 10*i for i in 10 if i mod 2 == 0}
  33 t := {-1: -10, i: 10*i for i in 10}
  34 ```
  35 
  36 ## Accessing Values
  37 
  38 Table values can be accessed with square bracket indexing. The result is an
  39 optional value:
  40 
  41 ```tomo
  42 table := {"A": 1, "B": 2}
  43 assert table["A"] == 1
  44 assert table["missing"] == none
  45 ```
  46 
  47 As with all optional values, you can use the `!` postfix operator to assert
  48 that the value is non-none (and create a runtime error if it is), or you can
  49 use the `or` operator to provide a fallback value in the case that it's none:
  50 
  51 ```tomo
  52 assert table["A"]! == 1
  53 
  54 assert (table["missing"] or -1) == -1
  55 ```
  56 
  57 ### Fallback Tables
  58 
  59 Tables can specify a fallback table that is used when looking up a value if it
  60 is not found in the table itself:
  61 
  62 ```tomo
  63 t := {"A": 10}
  64 t2 := {"B": 20; fallback=t}
  65 assert t2["A"] == 10
  66 ```
  67 
  68 The fallback is available by the `.fallback` field, which returns an optional
  69 table value:
  70 
  71 ```tomo
  72 assert t2.fallback == {"A": 10}
  73 assert t.fallback == none
  74 ```
  75 
  76 ### Default Values
  77 
  78 Tables can specify a default value which will be returned if a value is not
  79 present in the table or its fallback (if any).
  80 
  81 ```tomo
  82 counts := &{"foo": 12; default=0}
  83 assert counts["foo"] == 12
  84 assert counts["baz"] == 0
  85 counts["baz"] += 1
  86 assert counts["baz"] == 1
  87 ```
  88 
  89 When values are accessed from a table with a default value, the return type
  90 is non-optional (because a value will always be present).
  91 
  92 ## Setting Values
  93 
  94 You can assign a new key/value mapping or overwrite an existing one using
  95 `.set(key, value)` or an `=` assignment statement:
  96 
  97 ```tomo
  98 t := {"A": 1, "B": 2}
  99 t["B"] = 222
 100 t["C"] = 333
 101 assert t == {"A": 1, "B": 222, "C": 333}
 102 ```
 103 
 104 ## Length
 105 
 106 Table length can be accessed by the `.length` field:
 107 
 108 ```tomo
 109 assert {"A": 10, "B": 20}.length == 2
 110 ```
 111 
 112 ## Accessing Keys and Values
 113 
 114 The keys and values of a table can be efficiently accessed as lists using a
 115 constant-time immutable slice of the internal data from the table:
 116 
 117 ```tomo
 118 t := {"A": 10, "B": 20}
 119 assert t.keys == ["A", "B"]
 120 assert t.values == [10, 20]
 121 ```
 122 
 123 ## Iteration
 124 
 125 You can iterate over the key/value pairs in a table like this:
 126 
 127 ```tomo
 128 for key, value in table
 129     ...
 130 
 131 for key in table
 132     ...
 133 ```
 134 
 135 Table iteration operates over the value of the table when the loop began, so
 136 modifying the table during iteration is safe and will not result in the loop
 137 iterating over any of the new values.
 138 
 139 ## Sets
 140 
 141 For an interface similar to Python's Sets, Tomo tables can be used with an
 142 empty struct as its value type. For convenience, if a value or value is
 143 omitted, Tomo will assign a default value type of `struct Present()` (an empty
 144 struct). This way, the values stored in the table take up no space, but you
 145 still have an easy way to represent Set-like data.
 146 
 147 ```tomo
 148 nums := {10, 20, 30, 10}
 149 assert nums.items == [10, 20, 30]
 150 assert nums[10] == Present()
 151 assert nums[99] == none
 152 ```
 153 
 154 The following set-theoretic operations are available for tables:
 155 
 156 - Set union: (AKA `or`) `{10, 20, 30}.with({30, 40})` -> `{10, 20, 30, 40}`
 157 - Set intersection (AKA `and`) `{10, 20, 30}.intersection({30, 40})` -> `{10,
 158   20, 30, 40}`
 159 - Set difference (AKA, `xor`, disjunctive union, symmetric difference) `{10,
 160   20, 30}.difference({30, 40})` -> `{10, 20, 40}`
 161 - Set subtraction (AKA, `-`, asymmetric difference) `{10, 20, 30}.without({30,
 162   40})` -> `{10, 20}`
 163 
 164 # API
 165 
 166 [API documentation](../api/tables.md)