∑ Home ◇ Math ◇ Computing ◇ Arts ◇ Words ◇ Literature ◇ Music ◆

Emacs Lisp Tutorial: List ＆ Vector

Xah Lee, 2011-02-21, 2011-05-17

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.

Vectors

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

(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)

You can also use “while”. Example:

(setq v [3 4 5])
(setq i 0)
(while (< i (length v))
  (insert (format "%i" (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”, e.g. (append myVector nil).

List

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)"

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")

Examples:

(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")

The weird names “car”, “cdr”, and “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”.

; add one to each list member
(mapcar (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)
(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
(mapcar 'my-update-html-footer
        (list
"~/web/3d/viz.html"
"~/web/3d/viz2.html"
"~/web/dinju/Khajuraho.html"
"~/web/dinju/Khajuraho2.html"
"~/web/dinju/Khajuraho3.html"
        )
)

The “lambda” above pretty much means “subroutine”. It essentially let you define a function in the middle of your code. The form is (lambda arguments body). For example, (lambda (x y) (+ x y)) would be 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 mylist
; prepend it to mylist2
; resulting a reversed list
(let (mylist mylist2)
  (setq mylist '(a b c))
  (setq mylist2 '())
  (while mylist
    (setq mylist2
          (cons (pop mylist) mylist2)
    )
  )
  mylist2
)

First, use “let” to set a code block, with temporary variables “mylist” and “mylist2”. “mylist” is then set to '(a b c). “mylist2” 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 mylist) mylist2) creates a list with the new element prepended to “mylist2”. (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:

• vector has constant time access to any element.
• For list, it takes proportionally longer time to access a long list.
• list's length can grow by pre-pending with “cons” and is fast. “vector”'s length cannot change.

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

;; mixed nested list and vector
[ '(3 4) '(5 8) [4 2]]
(list [8 7] '(4 1))

Pairs: Association List ＆ Hash Table

Another important datatype similar to list and vector is called Association List, aka alist. It is similar to Python's dictionary or Perl's hash table or PHP's array. See: (info "(elisp) Association Lists").

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