Emacs Lisp: List

By Xah Lee. Date: . Last updated: .

Emacs Lisp's list datatype is known as linked list in computer science. lisp list are nested Cons Pair.

Here's a high-level tutorial on how to use it.

Create List

To create a list, write it like this (list a b etc).

; assign a list to a var
(setq mylist (list 1 "b" 3))
; prints a list
(message "%S" mylist)

If you do not want the elements evaluated, write it like this:

'(a b etc)

This is equivalent to

(quote (a b etc))

; assign a list to a var
(setq mylist '(a b c))

; prints a list
(message "%S" mylist)
;; create a list of values of variables
(let ((x 3) (y 4) (z 5))
  (message "%S" (list x y z))
  ) ; prints "(3 4 5)"
(make-list LENGTH INIT)
Create a list of length LENGTH, and all elements with value INIT.
(make-list 4 0) ;; (0 0 0 0)

Empty List, nil

In elisp, empty list is equivalent to nil. The following are all equivalent.

(eq '() (list ) ) ; t
(eq '() nil); t
(eq (list ) nil ) ; t

[see Emacs Lisp: Test Equality]

Create List of Numbers (Range Function)

(number-sequence n m step)
Return a list of a range of numbers, from n to m, in increment of step.
(number-sequence n m)
Default step 1.
(number-sequence n)
Return a list of 1 element of value n.
;; creating a range of numbers

;; just 1 element
(number-sequence 5) ; (5)

;; n to m, inclusive
(number-sequence 2 5) ; (2 3 4 5)

;; using 3 as step
(number-sequence 0 9 3) ; (0 3 6 9)

;; step can be negative
(number-sequence 5 0 -1) ; (5 4 3 2 1 0)

;; boundaries can be float but will not include
(number-sequence 2.2 5.3) ; (2.2 3.2 4.2 5.2)


(length list)
return number of elements.
(length '("a" "b" "c") ) ; 3

Get 1 Element from a List

(car list)
first element
(nth n list)
nth element. Index starts from 0.
(car (last list))
last element
(car (list "a" "b" "c") )   ; "a"
(nth 1 (list "a" "b" "c") ) ; "b"
(car (last (list "a" "b" "c")) )   ; "c"

Get Sublist

(cdr list)
2nd to last elements.
(nthcdr n list)
nth to last elements.
(butlast list n)
without the last n elements.
(cdr (list "a" "b" "c") )   ; ("b" "c")
(butlast (list "a" "b" "c" "d") )   ; ("a" "b" "c")
(butlast (list "a" "b" "c" "d") 2)   ; ("a" "b")

Prepend to list

(cons x list)
Return a new list, with x added to front. (prepend)
(cons "a" (list "c" "d") ) ; ("a" "c" "d")

(cons (list "a" "b") (list "c" "d") ) ; (("a" "b") "c" "d")

Append, Join Lists

(append sequence1 sequence2 etc)
join any sequence types and return a list. Warning: if you want it to return a proper list, the last element must be a list, or nil.
 (list 1 2 3 4)
 (append (list 1 2) (list 3 4))
;; t

Modify List Variable

(push list)
Add a element to the front variable. Returns the new list.
(pop list)
Remove first element from the variable. Returns the removed element.
(nbutlast list n)
Remove last n elements from the variable. Returns the new value of the variable.
(setcar list x)
Replace the first element in list with x. Returns x.
(setcdr list x)
Replace the rest of elements in list with x. Returns x.
(let ((x '(1)))
  (push 2 x)
  (equal x '(2 1)) ; true
(setq mylist '("a" "b" "c"))
(pop mylist)   ; "a"
(print mylist) ; ("b" "c")

The weird names {car, cdr, cons} are like that for historical reasons.

List to String

Ways to convert a list to string.

;; convert a list to string
(mapconcat 'number-to-string '(1 2 3) ",")
;; "1,2,3"
;; convert a list to string
(mapconcat 'identity '("a" "b" "c") ",")
;; "a,b,c"
;; convert list to string

(format "%s" '(1 "two" 3))
;; "(1 two 3)"

(substring (format "%s" '(1 "two" 3)) 1 -1)
;; "1 two 3"


(info "(elisp) Lists")

Lisp Basics

Lisp Data Structure

ErgoEmacs mascot-s276x226
Buy Xah Emacs Tutorial

Lisp Basics


Lisp Data Structure


Lisp Symbol

Lisp Misc

Working with Elisp