(doc-group table
  «Tables of keys with associated values.»)

(defdoc (del! table key)
  «Remove any existing mapping for `key` and return the table.»
  :doc-example
  «(def t #table(a 1 b 2))
   (del! t 'c)
   ; ↳ #table(b 2  a 1)
   (del! t 'b)
   ; ↳ #table(a 1)
   t
   ; ↳ #table(a 1)»
  :doc-group table
  :doc-see has?
  :doc-see get
  :doc-see put!)

(defdoc (get table key [failed-result])
  «Return the value associated with the `key` in the table.

   If the key isn't in the table then either return the optional
   `failed-result` argument or (if called without the argument) throw a
   `key-error` exception.»
  :doc-example
  «(def t #table(a 1 b 2))
   (get t 'a)
   ; ↳ 1
   (get t 'b NIL)
   ; ↳ 2
   (get t 'c)
   ; ‼ key not found: a
   (get t 'c 123)
   ; ↳ 123»
  :doc-group table
  :doc-see has?
  :doc-see put!
  :doc-see del!)

(defdoc (put! table key value)
  «Store the value associated with the key and return the table.

   Any existing value associated with the key will be replaced.»
  :doc-example
  «(def t #table(a 1 b 2))
   (put! t 'c 3)
   ; ↳ #table(c 3  b 2  a 1)
   (put! t 'a "hello")
   ; ↳ #table(c 3  b 2  a "hello")»
  :doc-group table
  :doc-see get
  :doc-see has?
  :doc-see del!)

(defdoc (has? table key)
  «Return `T` if the table has a value associated with the key, `NIL` otherwise.»
  :doc-example
  «(def t #table(a 1 b 2))
   (has? t 'c)
   ; ↳ NIL
   (has? t 'a)
   ; ↳ T»
  :doc-group table
  :doc-see get
  :doc-see put!
  :doc-see del!)

(defdoc (table . rest)
  «Construct a table from keys from the arguments.

   Every two arguments are expected to be a key and a value associated
   with that key.»
  :doc-example
  «(table)
   ; ↳ #table()»
  :doc-example
  «(table 'a 1 'b 2)
   ; ↳ #table(a 1 b 2)»
  :doc-group table
  :doc-see get
  :doc-see put!)