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

(car list)
first element
(nth n list)
nth element
(car (last list))
last element

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

(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

(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)
Replace the first element in list with x. Returns x.
(setcdr list x)
Replace 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.

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

If you have a question, put $5 at patreon and message me on xah discord.
Or support me by Buy Xah Emacs Tutorial

Emacs Tutorial

Emacs Init

Emacs Keys

ELisp

ELisp Examples

ELisp Write Major Mode


ELisp

Basics

Basic Functions

Writing Command

Writing Script

Lisp Data Structure

Lisp Symbol

Elisp Misc