2011-02-21

emacs lisp: vectors & lists

Perm url with updates: http://xahlee.org/emacs/elisp_list_vector.html

Emacs Lisp Tutorial: List & Vector

Xah Lee, 2011-02-21

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

(info "(elisp) Vector Functions")

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)"
Some List Element Extraction Functions
FunctionPurpose
(car mylist)first element
(nth n mylist)nth element (start from 0)
(car (last mylist))last element
(cdr mylist)2nd to last elements
(nthcdr n mylist)nth to last elements
(butlast mylist 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
FunctionPurpose
(length mylist)number of elements
(cons x mylist)add x to front
(append mylist1 mylist2)join two lists

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")
Functions that modify a list variable
FunctionPurpose
(pop mylist)Remove first element from the variable. Returns the removed element.
(nbutlast mylist n)Remove last n elements from the variable. Returns the new value of the variable.
(setcar mylist x)replaces the first element in mylist with x. Returns x.
(setcdr mylist x)replaces the rest of elements in mylist with x. Returns x.

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
"/home/vicky/web/3d/viz.html"
"/home/vicky/web/3d/viz2.html"
"/home/vicky/web/dinju/Khajuraho.html"
"/home/vicky/web/dinju/Khajuraho2.html"
"/home/vicky/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” datatypes are also called “sequences”. Many functions, such as “elt”, “mapcar”, work on any sequence type. Here's their primary differences:

  • vector has constant time access to any element.
  • 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:

;; arbitrary nested list or vector
[ '(3 4) '(5 8) [4 2]]
(list [8 7] '(4 1))
(info "(elisp) Sequences Arrays Vectors")