Skip to main content

append

append Function

Syntax:

append &rest lists → result

Arguments and Values:

list—each must be a proper list except the last, which may be any object.

result—an object. This will be a list unless the last list was not a list and all preceding lists were null.

Description:

append returns a new list that is the concatenation of the copies. lists are left unchanged; the list structure of each of lists except the last is copied. The last argument is not copied; it becomes the cdr of the final dotted pair of the concatenation of the preceding lists, or is returned directly if there are no preceding non-empty lists.

Examples:

(append ’(a b c) ’(d e f) ’() ’(g)) → (A B C D E F G) 
(append ’(a b c) ’d) → (A B C . D) 
(setq lst ’(a b c)) → (A B C) 
(append lst ’(d)) → (A B C D) 
lst → (A B C) 
(append) → NIL 
(append ’a) → A

See Also:

nconc, concatenate

Expanded Reference: append​

Concatenating two lists​

append returns a new list that is the concatenation of its arguments. All arguments except the last are copied.

(append '(a b c) '(d e f))
=> (A B C D E F)

Concatenating multiple lists​

append accepts any number of arguments.

(append '(1 2) '(3 4) '(5 6))
=> (1 2 3 4 5 6)

(append '(a) '(b) '(c) '(d))
=> (A B C D)

append does not modify the original lists​

All arguments except the last are copied. The original lists remain unchanged.

(let ((x '(1 2 3))
      (y '(4 5 6)))
  (append x y)
  (values x y))
=> (1 2 3)
=> (4 5 6)

The last argument is shared, not copied​

The last argument becomes the tail of the result without being copied. This means mutations to the last argument's structure will be visible through the result.

(let* ((tail (list 4 5))
       (result (append '(1 2 3) tail)))
  (setf (car tail) 40)
  result)
=> (1 2 3 40 5)

append with NIL arguments​

NIL arguments are effectively skipped.

(append nil '(a b c))
=> (A B C)

(append '(a b c) nil)
=> (A B C)

(append nil nil nil)
=> NIL

The last argument need not be a list​

If the last argument is not a list, the result is a dotted list.

(append '(a b c) 'd)
=> (A B C . D)

(append '(1 2) 3)
=> (1 2 . 3)

append with no arguments​

Calling append with no arguments returns NIL.

(append)
=> NIL