Emacs Lisp: List

By Xah Lee. Date: . Last updated: .

This page is a basic tutorial of Emacs Lisp's list datatype.

Create List

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

; 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 …). This is equivalent to (quote (list a b …))

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

Create Number Sequence (aka Range Function)

(number-sequence n m step) → returns 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) → returns 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

(length list) → return number of elements.

(length '("a" "b" "c") ) ; 3

Get Elements of a List

List index count starts from 0.

list element extraction functions
FunctionPurpose
(car list)first element
(nth n list)nth element
(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"
sublist functions
FunctionPurpose
(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

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

Join List
FunctionPurpose
(append list1 list2)Return a new list, join two lists
(equal
 (list 1 2 3 4)
 (append (list 1 2) (list 3 4))
 )
;; t

Modify List Variable

Functions that modify a list variable
FunctionPurpose
(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)replaces the first element in list with x. Returns x.
(setcdr list x)replaces 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.

(info "(elisp) Lists")

Map / Loop Thru List

Emacs Lisp: Map / Loop Thru List / Vector

List vs Vector

Emacs Lisp: List vs Vector

Association List (alist)

Another important datatype similar to list & 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.

Like it? Buy Xah Emacs Tutorial. Thanks.

or, buy something from my keyboard store.