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.clear()

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}
    >> t.get("A")
    = 1?

    >> t.get("????")
    = none

    >> t.get("A")!
    = 1

    >> 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)
    >> t
    = &{"A": @[1, 2, 3, 4], "B": @[99]}

    >> t.get_or_set("C", @[0, 0, 0])
    = @[0, 0, 0]
    >> 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: |
    >> {"A": 1, "B": 2}.has("A")
    = yes
    >> {"A": 1, "B": 2}.has("xxx")
    = no

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")
    >> 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)
    >> t
    = {"A": 1, "B": 2, "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"})
    >> t2["B"]
    = 3?
    t3 = t.with_fallback(none)
    >> t2["B"]
    = none