list, list

list, list*∗ Function*

Syntax:

list &rest objects → list

list* &rest objects⁺ → result

Arguments and Values:

object—an object.

list—a list.

result—an object.

Description:

list returns a list containing the supplied objects.

list* is like list except that the last argument to list becomes the car of the last cons constructed, while the last argument to list* becomes the cdr of the last cons constructed. Hence, any given call to list* always produces one fewer conses than a call to list with the same number of arguments.

If the last argument to list* is a list, the effect is to construct a new list which is similar, but which has additional elements added to the front corresponding to the preceding arguments of list*.

If list* receives only one object, that object is returned, regardless of whether or not it is a list.

Examples:

(list 1) → (1) 
(list\* 1) → 1 
(setq a 1) → 1 
(list a 2) → (1 2) 
’(a 2) → (A 2) 
(list ’a 2) → (A 2) 
(list\* a 2) → (1 . 2) 
(list) → NIL ;*i.e.*, () 
(setq a ’(1 2)) → (1 2) 
(eq a (list\* a)) → true 
(list 3 4 ’a (car ’(b . c)) (+ 6 -2)) → (3 4 A B 4) 
(list\* ’a ’b ’c ’d) *≡* (cons ’a (cons ’b (cons ’c ’d))) → (A B C . D) 
(list\* ’a ’b ’c ’(d e f)) → (A B C D E F) 

See Also:

cons

Notes:

(list* x) ≡ x

Expanded Reference: list, list*

Creating a simple list with list

list constructs a proper list from its arguments.

(list 1 2 3)
=> (1 2 3)

(list 'a 'b 'c)
=> (A B C)

(list)
=> NIL

list always creates a proper list

Every call to list produces a proper list terminated by NIL.

(list 1)
=> (1)

(list 'a '(b c) 3)
=> (A (B C) 3)

(cdr (last (list 1 2 3)))
=> NIL

Creating a dotted list with list*

list* is like list, but the last argument becomes the cdr of the last cons cell rather than being wrapped in one.

(list* 1 2)
=> (1 . 2)

(list* 1 2 3)
=> (1 2 . 3)

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

list* with one argument returns that argument

When called with a single argument, list* returns it directly without consing.

(list* 'a)
=> A

(list* '(1 2 3))
=> (1 2 3)

Practical use: building argument lists with list*

list* is useful for prepending known arguments to a rest-argument list, for example when calling apply.

(apply #'+ (list* 1 2 '(3 4 5)))
=> 15

;; Equivalent to (apply #'+ '(1 2 3 4 5))

list evaluates its arguments

Unlike the quote form, list evaluates each of its arguments.

(let ((x 10) (y 20))
  (list x y (+ x y)))
=> (10 20 30)