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

list of Numbers (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 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
(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
(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

(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
(append list1 list2)Return a new list, join two lists
 (list 1 2 3 4)
 (append (list 1 2) (list 3 4))
;; t

Modify List Variable

Functions that modify a list variable
(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")

List to String

Ways to convert a list to string.

;; convert a list to string
(mapconcat 'identity '("ab" "cd" "ef") ",")
;; "ab,cd,ef"
;; convert list to string

(format "%s" '(1 "two" 3))
;; "(1 two 3)"

(substring (format "%s" '(1 "two" 3)) 1 -1)
;; "1 two 3"

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 my tutorial? Put $5 at patreon

Or Buy Xah Emacs Tutorial

Or buy a nice keyboard: Best Keyboard for Emacs

Ask me question on patreon