code / tomo

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