Skip to main content

listp

listp Function

Syntax:

listp object → generalized-boolean

Arguments and Values:

object—an object.

generalized-boolean—a generalized boolean.

Description:

Returns true if object is of type list; otherwise, returns false.

Examples:

(listp nil) → true 
(listp (cons 1 2)) → true 
(listp (make-array 6)) → false 
(listp t) → false

See Also:

consp

Notes:

If object is a cons, listp does not check whether object is a proper list; it returns true for any kind of list.

(listp object) ≡ (typep object ’list) ≡ (typep object ’(or cons null))

Expanded Reference: listp​

Testing if an object is a list​

listp returns true if its argument is either a cons or NIL (the empty list).

(listp '(1 2 3))
=> T

(listp nil)
=> T

(listp '())
=> T

Non-list objects return NIL​

Numbers, strings, symbols (other than NIL), arrays, and other non-list objects all fail the test.

(listp 42)
=> NIL

(listp "hello")
=> NIL

(listp 'foo)
=> NIL

(listp (make-array 3))
=> NIL

listp does not check for proper lists​

listp returns true for dotted lists and even for the cons cells that form circular lists. It only checks whether the object is a cons or NIL.

(listp '(a . b))
=> T

(listp '(1 2 . 3))
=> T

Difference from consp​

The only difference between listp and consp is their treatment of NIL. listp considers NIL a list; consp does not.

(listp nil)
=> T

(consp nil)
=> NIL

(listp '(a))
=> T

(consp '(a))
=> T

Using listp for input validation​

listp can be used to validate that an argument is a list before processing it.

(defun safe-length (x)
  "Return the length if x is a proper list, or :not-a-list otherwise."
  (if (listp x)
      (list-length x)
      :not-a-list))

(safe-length '(a b c))
=> 3

(safe-length 42)
=> :NOT-A-LIST