Table.clear:
  short: clear a table
  description: >
    Removes all key-value pairs from the table.
  return:
    type: 'Void'
    description: >
      Nothing.
  args:
    t:
      type: '&{K:V}'
      description: >
        The reference to the table.
  example: |
    t := &{"A":1}
    t.clear()
    assert t == {}

Table.difference:
  short: return a table using keys not present in both tables
  description: >
    Return a table whose key/value pairs correspond to keys only present in one
    table, but not the other.
  return:
    type: '{K:V}'
    description: >
      A table containing the common key/value pairs whose keys only appear in
      one table.
  args:
    t:
      type: '{K:V}'
      description: >
        The base table.
    other:
      type: '{K:V}'
      description: >
        The other table.
  example: |
    t1 := {"A": 1; "B": 2, "C": 3}
    t2 := {"B": 2, "C":30, "D": 40}
    assert t1.difference(t2) == {"A": 1, "D": 40}

Table.get:
  short: get an item from a table
  description: >
    Retrieves the value associated with a key, or returns `none` if the key is not present.
  note: >
    Default values for the table are ignored.
  return:
    type: 'V?'
    description: >
      The value associated with the key or `none` if the key is not found.
  args:
    t:
      type: '{K:V}'
      description: >
        The table.
    key:
      type: 'K'
      description: >
        The key whose associated value is to be retrieved.
  example: |
    t := {"A": 1, "B": 2}
    assert t.get("A") == 1
    assert t.get("????") == none
    assert t.get("A")! == 1
    assert t.get("????") or 0 == 0

Table.get_or_set:
  short: get an item or set a default if absent
  description: >
    If the given key is in the table, return the associated value. Otherwise,
    insert the given default value into the table and return it.
  note: >
    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.

    The default value is only evaluated if the key is missing.
  return:
    type: 'V?'
    description: >
      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.
  args:
    t:
      type: "&{K:V}"
      description: >
        The table.
    key:
      type: "K"
      description: >
        The key whose associated value is to be retrieved.
    default:
      type: "V"
      description: >
        The default value to insert and return if the key is not present in the table.
  example: |
    t := &{"A": @[1, 2, 3]; default=@[]}
    t.get_or_set("A").insert(4)
    t.get_or_set("B").insert(99)
    assert t == &{"A": @[1, 2, 3, 4], "B": @[99]}

    assert t.get_or_set("C", @[0, 0, 0]) == @[0, 0, 0]
    assert t == &{"A": @[1, 2, 3, 4], "B": @[99], "C": @[0, 0, 0]}

Table.has:
  short: check for a key
  description: >
    Checks if the table contains a specified key.
  return:
    type: 'Bool'
    description: >
      `yes` if the key is present, `no` otherwise.
  args:
    t:
      type: '{K:V}'
      description: >
        The table.
    key:
      type: 'K'
      description: >
        The key to check for presence.
  example: |
    assert {"A": 1, "B": 2}.has("A") == yes
    assert {"A": 1, "B": 2}.has("xxx") == no

Table.intersection:
  short: return a table with common key/value pairs from two tables
  description: >
    Return a table with only the matching key/value pairs that are common to
    both tables.
  return:
    type: '{K:V}'
    description: >
      A table containing the common key/value pairs shared between two tables.
  args:
    t:
      type: '{K:V}'
      description: >
        The base table.
    other:
      type: '{K:V}'
      description: >
        The other table.
  example: |
    t1 := {"A": 1; "B": 2, "C": 3}
    t2 := {"B": 2, "C":30, "D": 40}
    assert t1.intersection(t2) == {"B": 2}

Table.remove:
  short: remove a table entry
  description: >
    Removes the key-value pair associated with a specified key.
  return:
    type: 'Void'
    description: >
      Nothing.
  args:
    t:
      type: '{K:V}'
      description: >
        The reference to the table.
    key:
      type: 'K'
      description: >
        The key of the key-value pair to remove.
  example: |
    t := {"A": 1, "B": 2}
    t.remove("A")
    assert t == {"B": 2}

Table.set:
  short: set a table entry
  description: >
    Sets or updates the value associated with a specified key.
  return:
    type: 'Void'
    description: >
      Nothing.
  args:
    t:
      type: '{K:V}'
      description: >
        The reference to the table.
    key:
      type: 'K'
      description: >
        The key to set or update.
    value:
      type: 'V'
      description: >
        The value to associate with the key.
  example: |
    t := {"A": 1, "B": 2}
    t.set("C", 3)
    assert t == {"A": 1, "B": 2, "C": 3}

Table.with:
  short: return a table with values added from another table
  description: >
    Return a copy of a table with values added from another table
  return:
    type: '{K:V}'
    description: >
      The original table, but with values from the other table added.
  args:
    t:
      type: '{K:V}'
      description: >
        The base table.
    other:
      type: '{K:V}'
      description: >
        The other table from which new key/value pairs will be added.
  example: |
    t := {"A": 1; "B": 2}
    assert t.with({"B": 20, "C": 30}) == {"A": 1, "B": 20, "C": 30}

Table.without:
  short: return a table without key/value pairs in another table
  description: >
    Return a copy of a table, but without any of the exact key/value pairs
    found in the other table.
  note: >
    Only exact key/value pairs will be discarded. Keys with a non-matching
    value will be kept.
  return:
    type: '{K:V}'
    description: >
      The original table, but without the key/value pairs from the other table.
  args:
    t:
      type: '{K:V}'
      description: >
        The base table.
    other:
      type: '{K:V}'
      description: >
        The other table whose key/value pairs will be omitted.
  example: |
    t := {"A": 1; "B": 2, "C": 3}
    assert t.without({"B": 2, "C": 30, "D": 40}) == {"A": 1, "C": 3}

Table.with_fallback:
  short: return a table with a new fallback
  description: >
    Return a copy of a table with a different fallback table.
  return:
    type: '{K:V}'
    description: >
      The original table with a different fallback.
  args:
    t:
      type: '{K:V}'
      description: >
        The table whose fallback will be replaced.
    fallback:
      type: '{K:V}?'
      description: >
        The new fallback table value.
  example: |
    t := {"A": 1; fallback={"B": 2}}
    t2 = t.with_fallback({"B": 3"})
    assert t2["B"] == 3
    t3 = t.with_fallback(none)
    assert t2["B"] == none