5.5 Building Cons Cells and Lists

Many functions build lists, as lists reside at the very heart of Lisp. cons is the fundamental list-building function; however, it is interesting to note that list is used more times in the source code for Emacs than cons.

Function: cons object1 object2

This function is the fundamental function used to build new list structure. It creates a new cons cell, making object1 the CAR, and object2 the CDR. It then returns the new cons cell. The arguments object1 and object2 may be any Lisp objects, but most often object2 is a list.

(cons 1 '(2)) => (1 2) (cons 1 '()) => (1) (cons 1 2) => (1 . 2)

cons is often used to add a single element to the front of a list. This is called consing the element onto the list. (1) For example:

(setq list (cons newelt list))

Note that there is no conflict between the variable named list used in this example and the function named list described below; any symbol can serve both purposes.

Macro: push newelt listname

This macro provides an alternative way to write (setq listname (cons newelt listname)). It is new in Emacs 21.

(setq l '(a b)) => (a b) (push 'c l) => (c a b) l => (c a b)

Function: list &rest objects

This function creates a list with objects as its elements. The resulting list is always nil-terminated. If no objects are given, the empty list is returned.

(list 1 2 3 4 5) => (1 2 3 4 5) (list 1 2 '(3 4 5) 'foo) => (1 2 (3 4 5) foo) (list) => nil

Function: make-list length object

This function creates a list of length elements, in which each element is object. Compare make-list with make-string (see section 4.3 Creating Strings).

(make-list 3 'pigs) => (pigs pigs pigs) (make-list 0 'pigs) => nil (setq l (make-list 3 '(a b)) => ((a b) (a b) (a b)) (eq (car l) (cadr l)) => t

Function: append &rest sequences

This function returns a list containing all the elements of sequences. The sequences may be lists, vectors, bool-vectors, or strings, but the last one should usually be a list. All arguments except the last one are copied, so none of the arguments is altered. (See nconc in 5.6.3 Functions that Rearrange Lists, for a way to join lists with no copying.)

More generally, the final argument to append may be any Lisp object. The final argument is not copied or converted; it becomes the CDR of the last cons cell in the new list. If the final argument is itself a list, then its elements become in effect elements of the result list. If the final element is not a list, the result is a "dotted list" since its final CDR is not nil as required in a true list.

The append function also allows integers as arguments. It converts them to strings of digits, making up the decimal print representation of the integer, and then uses the strings instead of the original integers. Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now! The proper way to convert an integer to a decimal number in this way is with format (see section 4.7 Formatting Strings) or number-to-string (see section 4.6 Conversion of Characters and Strings).

Here is an example of using append:

(setq trees '(pine oak)) => (pine oak) (setq more-trees (append '(maple birch) trees)) => (maple birch pine oak) trees => (pine oak) more-trees => (maple birch pine oak) (eq trees (cdr (cdr more-trees))) => t

You can see how append works by looking at a box diagram. The variable trees is set to the list (pine oak) and then the variable more-trees is set to the list (maple birch pine oak). However, the variable trees continues to refer to the original list:

more-trees trees | | | --- --- --- --- -> --- --- --- --- --> | | |--> | | |--> | | |--> | | |--> nil --- --- --- --- --- --- --- --- | | | | | | | | --> maple -->birch --> pine --> oak

An empty sequence contributes nothing to the value returned by append. As a consequence of this, a final nil argument forces a copy of the previous argument:

trees => (pine oak) (setq wood (append trees nil)) => (pine oak) wood => (pine oak) (eq wood trees) => nil

This once was the usual way to copy a list, before the function copy-sequence was invented. See section 6. Sequences, Arrays, and Vectors.

Here we show the use of vectors and strings as arguments to append:

(append [a b] "cd" nil) => (a b 99 100)

With the help of apply (see section 12.5 Calling Functions), we can append all the lists in a list of lists:

(apply 'append '((a b c) nil (x y z) nil)) => (a b c x y z)

If no sequences are given, nil is returned:

(append) => nil

Here are some examples where the final argument is not a list:

(append '(x y) 'z) => (x y . z) (append '(x y) [z]) => (x y . [z])

The second example shows that when the final argument is a sequence but not a list, the sequence's elements do not become elements of the resulting list. Instead, the sequence becomes the final CDR, like any other non-list final argument.

Function: reverse list

This function creates a new list whose elements are the elements of list, but in reverse order. The original argument list is not altered.

(setq x '(1 2 3 4)) => (1 2 3 4) (reverse x) => (4 3 2 1) x => (1 2 3 4)

Function: remq object list

This function returns a copy of list, with all elements removed which are eq to object. The letter `q' in remq says that it uses eq to compare object against the elements of list.

(setq sample-list '(a b c a b c)) => (a b c a b c) (remq 'a sample-list) => (b c b c) sample-list => (a b c a b c)

The function delq offers a way to perform this operation destructively. See 5.7 Using Lists as Sets.