(doc-group list
  «Working with lists.»)

(defdoc NIL
  «An empty list.  Can be used as the opposite of T in boolean
   expressions.»
  :doc-example
  «(not NIL)
   ; ↳ T»
  :doc-example
  «(if NIL 'yes 'no)
   ; ↳ no»
  :doc-example
  «(car NIL)
   ; ↳ NIL»
  :doc-example
  «(cdr NIL)
   ; ↳ NIL»
  :doc-group list
  :doc-see T)

(defdoc (length seq)
  «Return the length of the sequence.

   String's length is measured in UTF-8 code points.  For tables the number
   of key-value pairs is returned.

   Note: for circular lists the result is `NIL`.  A type error exception is
   thrown on improper lists, which are not considered valid sequences.»
  :doc-example
  «(length "абвгд")
   ; ↳ 5»
  :doc-example
  «(length #(abc 123))
   ; ↳ 2»
  :doc-example
  «(length #table(0 a  1 b  2 c))
   ; ↳ 3»
  :doc-example
  «(length (arr 'u32 1 2 3 4))
   ; ↳ 4»
  :doc-example
  «(length '(1 2 3 4 5))
   ; ↳ 5»
  :doc-example
  «(length '(1 2 3 4 . 5)) ; improper list
   ; ‼ type error: expected cons, got fixnum: 5»
  :doc-example
  «(length '#0=(1 . #0#)) ; circular list
   ; ↳ NIL»
  :doc-group array
  :doc-group list
  :doc-group table
  :doc-see proper-list?)

(defdoc (assq key lst)
  «Return a pair of a matching key and the associated value, or `NIL` if
   none matched.  Keys are compared using `eq?`.»
  :doc-group list
  :doc-see assoc
  :doc-see assv)

(defdoc (memq item lst)
  «Return the tail of a list beginning with the item, or `NIL` otherwise.
   List elements are compared to the `item` using `eq?`.»
  :doc-group list
  :doc-see member
  :doc-see memv)