elisp: Sequence Functions
6.1 Sequences
=============
This section describes functions that accept any kind of sequence.
-- Function: sequencep object
This function returns ‘t’ if OBJECT is a list, vector, string,
bool-vector, or char-table, ‘nil’ otherwise.
-- Function: length sequence
This function returns the number of elements in SEQUENCE. If
SEQUENCE is a dotted list, a ‘wrong-type-argument’ error is
signaled. Circular lists may cause an infinite loop. For a
char-table, the value returned is always one more than the maximum
Emacs character code.
Definition of safe-length, for the related function
‘safe-length’.
(length '(1 2 3))
⇒ 3
(length ())
⇒ 0
(length "foobar")
⇒ 6
(length [1 2 3])
⇒ 3
(length (make-bool-vector 5 nil))
⇒ 5
See also ‘string-bytes’, in Text Representations.
If you need to compute the width of a string on display, you should
use ‘string-width’ (Size of Displayed Text), not ‘length’, since
‘length’ only counts the number of characters, but does not account for
the display width of each character.
-- Function: elt sequence index
This function returns the element of SEQUENCE indexed by INDEX.
Legitimate values of INDEX are integers ranging from 0 up to one
less than the length of SEQUENCE. If SEQUENCE is a list,
out-of-range values behave as for ‘nth’. Definition of
nth. Otherwise, out-of-range values trigger an
‘args-out-of-range’ error.
(elt [1 2 3 4] 2)
⇒ 3
(elt '(1 2 3 4) 2)
⇒ 3
;; We use ‘string’ to show clearly which character ‘elt’ returns.
(string (elt "1234" 2))
⇒ "3"
(elt [1 2 3 4] 4)
error→ Args out of range: [1 2 3 4], 4
(elt [1 2 3 4] -1)
error→ Args out of range: [1 2 3 4], -1
This function generalizes ‘aref’ (Array Functions) and
‘nth’ (Definition of nth).
-- Function: copy-sequence sequence
This function returns a copy of SEQUENCE. The copy is the same
type of object as the original sequence, and it has the same
elements in the same order.
Storing a new element into the copy does not affect the original
SEQUENCE, and vice versa. However, the elements of the new
sequence are not copies; they are identical (‘eq’) to the elements
of the original. Therefore, changes made within these elements, as
found via the copied sequence, are also visible in the original
sequence.
If the sequence is a string with text properties, the property list
in the copy is itself a copy, not shared with the original’s
property list. However, the actual values of the properties are
shared. Text Properties.
This function does not work for dotted lists. Trying to copy a
circular list may cause an infinite loop.
DONTPRINTYET See also ‘append’ in Building Lists, ‘concat’ in *noteDONTPRINTYET See also ‘append’ in Building Lists, ‘concat’ in
Creating Strings, and ‘vconcat’ in Vector Functions, for
other ways to copy sequences.
(setq bar '(1 2))
⇒ (1 2)
(setq x (vector 'foo bar))
⇒ [foo (1 2)]
(setq y (copy-sequence x))
⇒ [foo (1 2)]
(eq x y)
⇒ nil
(equal x y)
⇒ t
(eq (elt x 1) (elt y 1))
⇒ t
;; Replacing an element of one sequence.
(aset x 0 'quux)
x ⇒ [quux (1 2)]
y ⇒ [foo (1 2)]
;; Modifying the inside of a shared element.
(setcar (aref x 1) 69)
x ⇒ [quux (69 2)]
y ⇒ [foo (69 2)]
-- Function: reverse sequence
This function creates a new sequence whose elements are the
elements of SEQUENCE, but in reverse order. The original argument
SEQUENCE is _not_ altered. Note that char-tables cannot be
reversed.
(setq x '(1 2 3 4))
⇒ (1 2 3 4)
(reverse x)
⇒ (4 3 2 1)
x
⇒ (1 2 3 4)
(setq x [1 2 3 4])
⇒ [1 2 3 4]
(reverse x)
⇒ [4 3 2 1]
x
⇒ [1 2 3 4]
(setq x "xyzzy")
⇒ "xyzzy"
(reverse x)
⇒ "yzzyx"
x
⇒ "xyzzy"
-- Function: nreverse sequence
This function reverses the order of the elements of SEQUENCE.
Unlike ‘reverse’ the original SEQUENCE may be modified.
For example:
(setq x '(a b c))
⇒ (a b c)
x
⇒ (a b c)
(nreverse x)
⇒ (c b a)
;; The cons cell that was first is now last.
x
⇒ (a)
To avoid confusion, we usually store the result of ‘nreverse’ back
in the same variable which held the original list:
(setq x (nreverse x))
Here is the ‘nreverse’ of our favorite example, ‘(a b c)’,
presented graphically:
Original list head: Reversed list:
------------- ------------- ------------
| car | cdr | | car | cdr | | car | cdr |
| a | nil |<-- | b | o |<-- | c | o |
| | | | | | | | | | | | |
------------- | --------- | - | -------- | -
| | | |
------------- ------------
For the vector, it is even simpler because you don’t need setq:
(setq x [1 2 3 4])
⇒ [1 2 3 4]
(nreverse x)
⇒ [4 3 2 1]
x
⇒ [4 3 2 1]
Note that unlike ‘reverse’, this function doesn’t work with
strings. Although you can alter string data by using ‘aset’, it is
strongly encouraged to treat strings as immutable.
-- Function: sort sequence predicate
This function sorts SEQUENCE stably. Note that this function
doesn’t work for all sequences; it may be used only for lists and
vectors. If SEQUENCE is a list, it is modified destructively.
This functions returns the sorted SEQUENCE and compares elements
using PREDICATE. A stable sort is one in which elements with equal
sort keys maintain their relative order before and after the sort.
Stability is important when successive sorts are used to order
elements according to different criteria.
The argument PREDICATE must be a function that accepts two
arguments. It is called with two elements of SEQUENCE. To get an
increasing order sort, the PREDICATE should return non-‘nil’ if the
first element is “less” than the second, or ‘nil’ if not.
The comparison function PREDICATE must give reliable results for
any given pair of arguments, at least within a single call to
‘sort’. It must be “antisymmetric”; that is, if A is less than B,
B must not be less than A. It must be “transitive”—that is, if A
is less than B, and B is less than C, then A must be less than C.
If you use a comparison function which does not meet these
requirements, the result of ‘sort’ is unpredictable.
The destructive aspect of ‘sort’ for lists is that it rearranges
the cons cells forming SEQUENCE by changing CDRs. A nondestructive
sort function would create new cons cells to store the elements in
their sorted order. If you wish to make a sorted copy without
destroying the original, copy it first with ‘copy-sequence’ and
then sort.
Sorting does not change the CARs of the cons cells in SEQUENCE; the
cons cell that originally contained the element ‘a’ in SEQUENCE
still has ‘a’ in its CAR after sorting, but it now appears in a
different position in the list due to the change of CDRs. For
example:
(setq nums '(1 3 2 6 5 4 0))
⇒ (1 3 2 6 5 4 0)
(sort nums '<)
⇒ (0 1 2 3 4 5 6)
nums
⇒ (1 2 3 4 5 6)
*Warning*: Note that the list in ‘nums’ no longer contains 0; this
is the same cons cell that it was before, but it is no longer the
first one in the list. Don’t assume a variable that formerly held
the argument now holds the entire sorted list! Instead, save the
result of ‘sort’ and use that. Most often we store the result back
into the variable that held the original list:
(setq nums (sort nums '<))
For the better understanding of what stable sort is, consider the
following vector example. After sorting, all items whose ‘car’ is
8 are grouped at the beginning of ‘vector’, but their relative
order is preserved. All items whose ‘car’ is 9 are grouped at the
end of ‘vector’, but their relative order is also preserved:
(setq
vector
(vector '(8 . "xxx") '(9 . "aaa") '(8 . "bbb") '(9 . "zzz")
'(9 . "ppp") '(8 . "ttt") '(8 . "eee") '(9 . "fff")))
⇒ [(8 . "xxx") (9 . "aaa") (8 . "bbb") (9 . "zzz")
(9 . "ppp") (8 . "ttt") (8 . "eee") (9 . "fff")]
(sort vector (lambda (x y) (< (car x) (car y))))
⇒ [(8 . "xxx") (8 . "bbb") (8 . "ttt") (8 . "eee")
(9 . "aaa") (9 . "zzz") (9 . "ppp") (9 . "fff")]
Sorting, for more functions that perform sorting. See
‘documentation’ in Accessing Documentation, for a useful
example of ‘sort’.
The ‘seq.el’ library provides the following additional sequence
manipulation macros and functions, prefixed with ‘seq-’. To use them,
you must first load the ‘seq’ library.
All functions defined in this library are free of side-effects; i.e.,
they do not modify any sequence (list, vector, or string) that you pass
as an argument. Unless otherwise stated, the result is a sequence of
the same type as the input. For those functions that take a predicate,
this should be a function of one argument.
The ‘seq.el’ library can be extended to work with additional types of
sequential data-structures. For that purpose, all functions are defined
using ‘cl-defgeneric’. Generic Functions, for more details
about using ‘cl-defgeneric’ for adding extensions.
-- Function: seq-elt sequence index
This function returns the element of SEQUENCE at the specified
INDEX, which is an integer whose valid value range is zero to one
less than the length of SEQUENCE. For out-of-range values on
built-in sequence types, ‘seq-elt’ behaves like ‘elt’. For the
details, see Definition of elt.
(seq-elt [1 2 3 4] 2)
⇒ 3
‘seq-elt’ returns places settable using ‘setf’ (Setting
Generalized Variables).
(setq vec [1 2 3 4])
(setf (seq-elt vec 2) 5)
vec
⇒ [1 2 5 4]
-- Function: seq-length sequence
This function returns the number of elements in SEQUENCE. For
built-in sequence types, ‘seq-length’ behaves like ‘length’.
Definition of length.
-- Function: seqp sequence
This function returns non-‘nil’ if SEQUENCE is a sequence (a list
or array), or any additional type of sequence defined via ‘seq.el’
generic functions.
(seqp [1 2])
⇒ t
(seqp 2)
⇒ nil
-- Function: seq-drop sequence n
This function returns all but the first N (an integer) elements of
SEQUENCE. If N is negative or zero, the result is SEQUENCE.
(seq-drop [1 2 3 4 5 6] 3)
⇒ [4 5 6]
(seq-drop "hello world" -4)
⇒ "hello world"
-- Function: seq-take sequence n
This function returns the first N (an integer) elements of
SEQUENCE. If N is negative or zero, the result is ‘nil’.
(seq-take '(1 2 3 4) 3)
⇒ (1 2 3)
(seq-take [1 2 3 4] 0)
⇒ []
-- Function: seq-take-while predicate sequence
This function returns the members of SEQUENCE in order, stopping
before the first one for which PREDICATE returns ‘nil’.
(seq-take-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
⇒ (1 2 3)
(seq-take-while (lambda (elt) (> elt 0)) [-1 4 6])
⇒ []
-- Function: seq-drop-while predicate sequence
This function returns the members of SEQUENCE in order, starting
from the first one for which PREDICATE returns ‘nil’.
(seq-drop-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
⇒ (-1 -2)
(seq-drop-while (lambda (elt) (< elt 0)) [1 4 6])
⇒ [1 4 6]
-- Function: seq-do function sequence
This function applies FUNCTION to each element of SEQUENCE in turn
(presumably for side effects), and returns SEQUENCE.
-- Function: seq-map function sequence
This function returns the result of applying FUNCTION to each
element of SEQUENCE. The returned value is a list.
(seq-map #'1+ '(2 4 6))
⇒ (3 5 7)
(seq-map #'symbol-name [foo bar])
⇒ ("foo" "bar")
-- Function: seq-mapn function &rest sequences
This function returns the result of applying FUNCTION to each
element of SEQUENCES. The arity (sub-arity What Is a
Function.) of FUNCTION must match the number of sequences. Mapping
stops at the end of the shortest sequence, and the returned value
is a list.
(seq-mapn #'+ '(2 4 6) '(20 40 60))
⇒ (22 44 66)
(seq-mapn #'concat '("moskito" "bite") ["bee" "sting"])
⇒ ("moskitobee" "bitesting")
-- Function: seq-filter predicate sequence
This function returns a list of all the elements in SEQUENCE for
which PREDICATE returns non-‘nil’.
(seq-filter (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
⇒ (1 3 5)
(seq-filter (lambda (elt) (> elt 0)) '(-1 -3 -5))
⇒ nil
-- Function: seq-remove predicate sequence
This function returns a list of all the elements in SEQUENCE for
which PREDICATE returns ‘nil’.
(seq-remove (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
⇒ (-1 -3)
(seq-remove (lambda (elt) (< elt 0)) '(-1 -3 -5))
⇒ nil
-- Function: seq-reduce function sequence initial-value
This function returns the result of calling FUNCTION with
INITIAL-VALUE and the first element of SEQUENCE, then calling
FUNCTION with that result and the second element of SEQUENCE, then
with that result and the third element of SEQUENCE, etc. FUNCTION
should be a function of two arguments. If SEQUENCE is empty, this
returns INITIAL-VALUE without calling FUNCTION.
(seq-reduce #'+ [1 2 3 4] 0)
⇒ 10
(seq-reduce #'+ '(1 2 3 4) 5)
⇒ 15
(seq-reduce #'+ '() 3)
⇒ 3
-- Function: seq-some predicate sequence
This function returns the first non-‘nil’ value returned by
applying PREDICATE to each element of SEQUENCE in turn.
(seq-some #'numberp ["abc" 1 nil])
⇒ t
(seq-some #'numberp ["abc" "def"])
⇒ nil
(seq-some #'null ["abc" 1 nil])
⇒ t
(seq-some #'1+ [2 4 6])
⇒ 3
-- Function: seq-find predicate sequence &optional default
This function returns the first element in SEQUENCE for which
PREDICATE returns non-‘nil’. If no element matches PREDICATE, the
function returns DEFAULT.
Note that this function has an ambiguity if the found element is
identical to DEFAULT, as in that case it cannot be known whether an
element was found or not.
(seq-find #'numberp ["abc" 1 nil])
⇒ 1
(seq-find #'numberp ["abc" "def"])
⇒ nil
-- Function: seq-every-p predicate sequence
This function returns non-‘nil’ if applying PREDICATE to every
element of SEQUENCE returns non-‘nil’.
(seq-every-p #'numberp [2 4 6])
⇒ t
(seq-some #'numberp [2 4 "6"])
⇒ nil
-- Function: seq-empty-p sequence
This function returns non-‘nil’ if SEQUENCE is empty.
(seq-empty-p "not empty")
⇒ nil
(seq-empty-p "")
⇒ t
-- Function: seq-count predicate sequence
This function returns the number of elements in SEQUENCE for which
PREDICATE returns non-‘nil’.
(seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2])
⇒ 2
-- Function: seq-sort function sequence
This function returns a copy of SEQUENCE that is sorted according
to FUNCTION, a function of two arguments that returns non-‘nil’ if
the first argument should sort before the second.
-- Function: seq-contains sequence elt &optional function
This function returns the first element in SEQUENCE that is equal
to ELT. If the optional argument FUNCTION is non-‘nil’, it is a
function of two arguments to use instead of the default ‘equal’.
(seq-contains '(symbol1 symbol2) 'symbol1)
⇒ symbol1
(seq-contains '(symbol1 symbol2) 'symbol3)
⇒ nil
-- Function: seq-position sequence elt &optional function
This function returns the index of the first element in SEQUENCE
that is equal to ELT. If the optional argument FUNCTION is
non-‘nil’, it is a function of two arguments to use instead of the
default ‘equal’.
(seq-position '(a b c) 'b)
⇒ 1
(seq-position '(a b c) 'd)
⇒ nil
-- Function: seq-uniq sequence &optional function
This function returns a list of the elements of SEQUENCE with
duplicates removed. If the optional argument FUNCTION is
non-‘nil’, it is a function of two arguments to use instead of the
default ‘equal’.
(seq-uniq '(1 2 2 1 3))
⇒ (1 2 3)
(seq-uniq '(1 2 2.0 1.0) #'=)
⇒ [3 4]
-- Function: seq-subseq sequence start &optional end
This function returns a subset of SEQUENCE from START to END, both
integers (END defaults to the last element). If START or END is
negative, it counts from the end of SEQUENCE.
(seq-subseq '(1 2 3 4 5) 1)
⇒ (2 3 4 5)
(seq-subseq '[1 2 3 4 5] 1 3)
⇒ [2 3]
(seq-subseq '[1 2 3 4 5] -3 -1)
⇒ [3 4]
-- Function: seq-concatenate type &rest sequences
This function returns a sequence of type TYPE made of the
concatenation of SEQUENCES. TYPE may be: ‘vector’, ‘list’ or
‘string’.
(seq-concatenate 'list '(1 2) '(3 4) [5 6])
⇒ (1 2 3 4 5 6)
(seq-concatenate 'string "Hello " "world")
⇒ "Hello world"
-- Function: seq-mapcat function sequence &optional type
This function returns the result of applying ‘seq-concatenate’ to
the result of applying FUNCTION to each element of SEQUENCE. The
result is a sequence of type TYPE, or a list if TYPE is ‘nil’.
(seq-mapcat #'seq-reverse '((3 2 1) (6 5 4)))
⇒ (1 2 3 4 5 6)
-- Function: seq-partition sequence n
This function returns a list of the elements of SEQUENCE grouped
into sub-sequences of length N. The last sequence may contain less
elements than N. N must be an integer. If N is a negative integer
or 0, the return value is ‘nil’.
(seq-partition '(0 1 2 3 4 5 6 7) 3)
⇒ ((0 1 2) (3 4 5) (6 7))
-- Function: seq-intersection sequence1 sequence2 &optional function
This function returns a list of the elements that appear both in
SEQUENCE1 and SEQUENCE2. If the optional argument FUNCTION is
non-‘nil’, it is a function of two arguments to use to compare
elements instead of the default ‘equal’.
(seq-intersection [2 3 4 5] [1 3 5 6 7])
⇒ (3 5)
-- Function: seq-difference sequence1 sequence2 &optional function
This function returns a list of the elements that appear in
SEQUENCE1 but not in SEQUENCE2. If the optional argument FUNCTION
is non-‘nil’, it is a function of two arguments to use to compare
elements instead of the default ‘equal’.
(seq-difference '(2 3 4 5) [1 3 5 6 7])
⇒ (2 4)
-- Function: seq-group-by function sequence
This function separates the elements of SEQUENCE into an alist
whose keys are the result of applying FUNCTION to each element of
SEQUENCE. Keys are compared using ‘equal’.
(seq-group-by #'integerp '(1 2.1 3 2 3.2))
⇒ ((t 1 3 2) (nil 2.1 3.2))
(seq-group-by #'car '((a 1) (b 2) (a 3) (c 4)))
⇒ ((b (b 2)) (a (a 1) (a 3)) (c (c 4)))
-- Function: seq-into sequence type
This function converts the sequence SEQUENCE into a sequence of
type TYPE. TYPE can be one of the following symbols: ‘vector’,
‘string’ or ‘list’.
(seq-into [1 2 3] 'list)
⇒ (1 2 3)
(seq-into nil 'vector)
⇒ []
(seq-into "hello" 'vector)
⇒ [104 101 108 108 111]
-- Function: seq-min sequence
This function returns the smallest element of SEQUENCE. The
elements of SEQUENCE must be numbers or markers (Markers).
(seq-min [3 1 2])
⇒ 1
(seq-min "Hello")
⇒ 72
-- Function: seq-max sequence
This function returns the largest element of SEQUENCE. The
elements of SEQUENCE must be numbers or markers.
(seq-max [1 3 2])
⇒ 3
(seq-max "Hello")
⇒ 111
-- Macro: seq-doseq (var sequence) body...
This macro is like ‘dolist’ (dolist Iteration.), except that
SEQUENCE can be a list, vector or string. This is primarily useful
for side-effects.
-- Macro: seq-let arguments sequence body...
This macro binds the variables defined in ARGUMENTS to the elements
of SEQUENCE. ARGUMENTS can themselves include sequences, allowing
for nested destructuring.
The ARGUMENTS sequence can also include the ‘&rest’ marker followed
by a variable name to be bound to the rest of ‘sequence’.
(seq-let [first second] [1 2 3 4]
(list first second))
⇒ (1 2)
(seq-let (_ a _ b) '(1 2 3 4)
(list a b))
⇒ (2 4)
(seq-let [a [b [c]]] [1 [2 [3]]]
(list a b c))
⇒ (1 2 3)
(seq-let [a b &rest others] [1 2 3 4]
others)
⇒ [3 4]
Info Catalog
elisp: Sequences Arrays Vectors
elisp: Arrays