Elisp: 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

Elisp: Map / Loop Thru List / Vector

List vs Vector

Elisp: Sequence: List, Array

Association List (alist)

〔►see Elisp: Association List

Data Structure Topic

  1. Elisp: Sequence: List, Array
  2. Elisp: Vector
  3. Elisp: List
  4. Elisp: Association List
  5. Elisp: Property List
  6. Elisp: Symbol Property List
  7. Elisp: Map / Loop Thru List / Vector
  8. Elisp: Filter a List
  9. Elisp: Hash Table
Like it? Buy Xah Emacs Tutorial. Thanks.