Elisp: List

By Xah Lee. Date: . Last updated: .

Emacs Lisp's list datatype is known as linked list in computer science.

Here's a high-level tutorial on how to use it.

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

(make-list LENGTH INIT) → create a list of length LENGTH, and all elements with value INIT.

(make-list 4 0) ;; (0 0 0 0)

Empty List, nil

In elisp, empty list is equivalent to nil. The following are all equivalent.

(eq '() (list ) ) ; t
(eq '() nil); t
(eq (list ) nil ) ; t

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

(length list) → return number of elements.

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

Get 1 Element from a List

List index count starts from 0.

(car (list "a" "b" "c") )   ; "a"
(nth 1 (list "a" "b" "c") ) ; "b"
(car (last (list "a" "b" "c")) )   ; "c"

Get Sublist

(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

(append sequence1 sequence2 …) → join any sequence types and return a list. Warning: if you want it to return a propert list, the last element must be a list, or nil.

(equal
 (list 1 2 3 4)
 (append (list 1 2) (list 3 4))
 )
;; t

Modify List Variable

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

List to String

Ways to convert a list to string.

;; convert a list to string
(mapconcat 'number-to-string '(1 2 3) ",")
;; "1,2,3"
;; convert a list to string
(mapconcat 'identity '("a" "b" "c") ",")
;; "a,b,c"
;; convert list to string

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

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

Reference

(info "(elisp) Lists")

Elisp Data Structure

  1. Sequence: List, Array
  2. Vector
  3. List
  4. Sequence Functions
  5. Map List/Vector
  6. Exit Loop/Function
  7. Association List
  8. Property List
  9. Symbol Property List
  10. Hash Table
Patreon me $5 patreon

Or Buy Xah Emacs Tutorial

Or buy a nice keyboard: Best Keyboard for Emacs

If you have a question, put $5 at patreon and message me.