Emacs Lisp: Sequence Functions

By Xah Lee. Date: . Last updated: .

Here's a collection of functions that works on Sequence type.

Note, this page does not include specialized functions for Association List nor Property List .

Create List

(number-sequence n m step)
returns a list of a range of numbers, from n to m, in increment of step.

Get Element from List

(car list)
first element
(cdr list)
rest elements
(nth n list)
nth element
(nthcdr N LIST)
rest starting at n.
(last LIST &optional N)
last as a list. i.e. return (cons lastElement nil). To get the actual last item of a list, do (car (last list))

Add to List

(cons x list)
Return a new list, with x added to left.
(add-to-list LIST-VAR ELEMENT &optional APPEND COMPARE-FN)
Add to list when not already in it.
(add-to-ordered-list LIST-VAR ELEMENT &optional ORDER)
Add to specific position in list, if it does not exist. The list is reordered.

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.

List to Vector

(vconcat sequence1 sequence2 etc)
Join any sequence types and return a vector.

Sequence to List

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

Sequence to String

(format "%s" sequence)
Return a string.

Sequence Functions

These functions work on any Sequence Type .

Those starting with “seq-” are new in emacs 25.1, released in 2016-09. They are from “seq.el”, and the file is loaded when emacs starts. You may want to explicitly declare (require 'seq).

Some of these provide new functionalities, some gives a unified interface to old functions.

Check Existence

(member x list)
Check if x is in list. If so, return a list starting with the first occurrence of object. Else return nil. Comparison done using equal. [see Emacs Lisp: Test Equality]
(member "4" '("3" "4" "5")) ;; ("4" "5")
(member-ignore-case x list)
same as member, except that x should be a string, and comparison ignores letter-case.
(member-ignore-case "A" '("b" "a")) ; ("a")
(memq x list)
Same as member, but comparison done using eq. Use this if all items are Symbols.
(memql x list)
Same as member, but comparison done using eql.

Delete Elements

(delete x sequence)
  • Remove all x in sequence.
  • The original sequence is destroyed if it's a list.
  • Returns a new sequence.
  • Comparison is done with equal. [see Emacs Lisp: Test Equality]
(setq xx '(3 4 5))

;; always set result to the same var. because original is usually destroyed
(setq xx (delete 4 xx)) ; (3 5)

;; on vector
(setq xx [3 4 5])
(setq xx (delete 4 xx)) ; [3 5]
(delq x sequence)
Same as delete, except the comparison is done with eq. Use this if all items are Symbols.
(setq xx '(3 4 5))

;; always set result to the same var
(setq xx (delq 4 xx)) ; (3 5)
(remove x sequence)
  • Remove all x in sequence.
  • The original sequence is unchanged.
  • Returns a new sequence.
  • Comparison is done with equal. [see Emacs Lisp: Test Equality]
(setq xx '(3 4 5))
(remove 4 xx) ;; (3 5)
xx ; (3 4 5)
(remq x list)
Same as remove, except the comparison is done with eq.
(setq xx '(3 4 5))
(remq 4 xx) ; (3 5)
xx ; (3 4 5)

Delete Duplicates

(delete-dups list)
This function destructively removes all duplicates from list, return a new list. The first one is kept among duplicates. Comparison done using equal. [see Emacs Lisp: Test Equality]
(setq xx '(3 4 5 3 2))
(setq xx (delete-dups xx)) ; (3 4 5 2)

Misc

Reference

Lisp Data Structure

ErgoEmacs mascot-s276x226
Buy Xah Emacs Tutorial

Lisp Basics

Basics

Lisp Data Structure

Function

Lisp Symbol

Lisp Misc

Working with Elisp