Emacs Lisp Tutorial: List & Vector

, ,

This page is a practical tutorial of Emacs Lisp's list and vector datatype. If you don't know elisp, first take a look at Emacs Lisp Basics.

Lisp has vector and list datatypes. These are similar to other language's {list, vector, array}.


Elisp has a “vector” datatype. It is similar to C or Java's “array”. It has a constant access time but you cannot add/remove element to it.

To create a vector, write it like this (vector a b …).

If you do not want the elements evaluated, write it like this: [a b …].

Creating a Vector

;; creating a vector
(setq v (vector 3 4 5)) ; each element will be evaluated
(setq v [3 4 5]) ; each element will NOT be evaluated


(length (vector 3 4 5))

Getting a Element

use elt.

(elt (vector 3 4 5) 0) ; ⇒ 3. index starts at 0

Changing a Element

use aset.

(setq v [3 4 5])
(aset v 0 "b")
v  ; ⇒ ["b" 4 5]

Nested Vector

;; nested vector
[[1 2] [3 4]] ; 2 by 2 matrix
[8 [3 [2 9] c] 7 [4 "b"]] ; random nested vector

Looping Thru Vector

One simple way to go thru a vector is using mapcar. Note that it returns a list, not vector.

;; add 1 to each
(mapcar '1+ [3 4 5] ) ; ⇒ (4 5 6)

;; get first element of each row
(mapcar (lambda (x) (elt x 0)) [[1 2] [3 4]] ) ; ⇒ (1 3)

If you want to map to list but don't need the return value, use mapc.

You can also use while. Example:

(setq v [3 4 5])
(setq i 0)

(while (< i (length v))
  (insert (format "%d" (elt v i)))
  (setq i (1+ i))
) ; inserts "345"

Join and Misc

You can join 2 vectors into a new vector by vconcat. You can convert a vector to list by append, ⁖ (append vec nil).

(info "(elisp) Vector Functions")


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

If you do not want the elements evaluated, write it like this: '(a b …).

; prints a list
(message "%S" '(a b c))

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

; create a list of values of variables
(let ((x 3) (y 4) (z 5))
  (message "%S" (list x y z))
) ; prints "(3 4 5)"
Some List Element Extraction Functions
(car )first element
(nth n )nth element (start from 0)
(car (last ))last element
(cdr )2nd to last elements
(nthcdr n )nth to last elements
(butlast n)without the last n elements

Here's some example of lists and element extraction.

(car (list "a" "b" "c") )   ; ⇒ "a"
(nth 1 (list "a" "b" "c") ) ; ⇒ "b"
(car (last (list "a" "b" "c")) )   ; ⇒ "c"

(cdr (list "a" "b" "c") )   ; ⇒ ("b" "c")
Basic List Functions
(length )number of elements
(cons x )add x to front
(append ℓ1 ℓ2)join two lists


(length (list "a" "b" "c") ) ; ⇒ 3

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

(append (list "a" "b") (list "c" "d") ) ; ⇒ ("a" "b" "c" "d")
Functions that modify a list variable
(pop )Remove first element from the variable. Returns the removed element.
(nbutlast n)Remove last n elements from the variable. Returns the new value of the variable.
(setcar x)replaces the first element in with x. Returns x.
(setcdr x)replaces the rest of elements in with x. Returns x.

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

(info "(elisp) Lists")

Looping Thru a List

Here's a typical way of going thru a list. It is done with mapcar or mapc. Use mapc when you don't need the return value.

; add one to each list member
 (lambda (x) (+ x 1))
 (list 1 2 3 4)
) ; ⇒ (2 3 4 5)

; add one to each list member using the build in function 1+
(mapcar '1+ (list 1 2 3 4)) ; ⇒ (2 3 4 5)

; take the 1st element of each element in the list
(mapcar 'car  '((1 2) (3 4) (5 6))) ; ⇒ (1 3 5)

; take the 2nd element of each element in the ilst
(mapcar (lambda (x) (nth 1 x))  '((1 2) (3 4) (5 6))) ; ⇒ (2 4 6)

; apply a file processing function to a list of files
(mapc 'my-update-html-footer

The lambda above means function. It let you define a function in the middle of your code. The form is (lambda (args) body). For example, (lambda (x y) (+ x y)) is a function that takes two arguments, x and y, and returns their sum.

Loop thru List with “while”

Another common form to loop thru a list is using the while function. In each iteration, pop is used to reduce the list. Here's a example of going thru a list using the while function.

(let (myList)
  (setq myList '(a b c))
  (while myList
     (message "%s" (pop myList))
     (sleep-for 1)

Following is another example of using while to loop thru a list.

;; pop head of l1
;; prepend it to l2
;; resulting a reversed list
(let (l1 l2)
  (setq l1 '(a b c))
  (setq l2 '())
  (while l1
    (setq l2
          (cons (pop l1) l2)

First, use let to set a code block, with temporary variables “l1” and “l2”. “l1” is then set to '(a b c). “l2” is set to a empty list. Then, in the body of while, the (pop myList) drops myList's first element and returns it, the (cons (pop l1) l2) creates a list with the new element prepended to “l2”. (Note: This code is to illustrate going thru a list. If you want to reverse a list, use the reverse function.)

List vs Vector

Lisp's list and vector both are subtypes of the “sequences” datatype. Many functions, such as {elt, mapcar}, work on any sequence type. Here's their primary differences:

Lisp culture is to almost always use list. I recommend using vector as much as possible. Use list ONLY IF you need to constantly grow the list. Even for that case, i recommend using vector by starting with large length, using the function make-vector. 〔☛ Guy Steele on Parallel Programing: Get rid of cons!

You can nest list and vectors in any way. Example:

;; mixed nested list/vector

[ '(3 4) '(5 8) [4 2]]

(list [8 7] '(4 1))

(info "(elisp) Sequences Arrays Vectors")

List of Pairs: Association List & Hash Table

Association List (alist)

Another important datatype similar to list and vector is called Association List (aka alist). It is similar to Python Dictionary, Ruby Hash Table. See: (info "(elisp) Association Lists").

For a example of using alist, see: Emacs Lisp: Batch Script to Validate Matching Brackets.

Hash Table

Elisp also has a true hash table, if you need large number of pairs. See: Emacs Lisp Hash Table.

blog comments powered by Disqus