Next: Arrays, Up: Sequences Arrays Vectors

This section describes functions that accept any kind of sequence.

— Function: **sequencep**` object`

This function returns

`t`

ifobjectis a list, vector, string, bool-vector, or char-table,`nil`

otherwise. See also`seqp`

below.

— Function: **length**` sequence`

This function returns the number of elements in

sequence. The function signals the`wrong-type-argument`

error if the argument is not a sequence or is a dotted list; it signals the`circular-list`

error if the argument is a circular list. For a char-table, the value returned is always one more than the maximum Emacs character code.See 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`

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

sequenceindexed byindex. Legitimate values ofindexare integers ranging from 0 up to one less than the length ofsequence. Ifsequenceis a list, out-of-range values behave as for`nth`

. See 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], -1This function generalizes

`aref`

(see Array Functions) and`nth`

(see Definition of nth).

— Function: **copy-sequence**` seqr`

This function returns a copy of

seqr, which should be either a sequence or a record. The copy is the same type of object as the original, and it has the same elements in the same order. However, ifseqris empty, like a string or a vector of zero length, the value returned by this function might not be a copy, but an empty object of the same type and identical toseqr.Storing a new element into the copy does not affect the original

seqr, and vice versa. However, the elements of the copy are not copies; they are identical (`eq`

) to the elements of the original. Therefore, changes made within these elements, as found via the copy, are also visible in the original.If the argument 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. See Text Properties.

This function does not work for dotted lists. Trying to copy a circular list may cause an infinite loop.

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 argumentsequenceisnotaltered. 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 originalsequencemay 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

sequencestably. Note that this function doesn't work for all sequences; it may be used only for lists and vectors. Ifsequenceis a list, it is modified destructively. This functions returns the sortedsequenceand compares elements usingpredicate. 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

predicatemust be a function that accepts two arguments. It is called with two elements ofsequence. To get an increasing order sort, thepredicateshould return non-`nil`

if the first element is “less” than the second, or`nil`

if not.The comparison function

predicatemust give reliable results for any given pair of arguments, at least within a single call to`sort`

. It must be antisymmetric; that is, ifais less thanb,bmust not be less thana. It must be transitive—that is, ifais less thanb, andbis less thanc, thenamust be less thanc. 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 formingsequenceby 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`

insequencestill 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")]See 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`

. See Generic Functions, for
more details about using `cl-defgeneric`

for adding extensions.

— Function: **seq-elt**` sequence index`

This function returns the element of

sequenceat the specifiedindex, which is an integer whose valid value range is zero to one less than the length ofsequence. 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`

(see 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`

. See Definition of length.

— Function: **seqp**` object`

This function returns non-

`nil`

ifobjectis a sequence (a list or array), or any additional type of sequence defined viaseq.elgeneric functions. This is an extensible variant of`sequencep`

.(seqp [1 2]) ⇒ t (seqp 2) ⇒ nil

— Function: **seq-drop**` sequence n`

This function returns all but the first

n(an integer) elements ofsequence. Ifnis negative or zero, the result issequence.(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 ofsequence. Ifnis 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

sequencein order, stopping before the first one for whichpredicatereturns`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

sequencein order, starting from the first one for whichpredicatereturns`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

functionto each element ofsequencein turn (presumably for side effects), and returnssequence.

— Function: **seq-map**` function sequence`

This function returns the result of applying

functionto each element ofsequence. 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-map-indexed**` function sequence`

This function returns the result of applying

functionto each element ofsequenceand its index withinseq. The returned value is a list.(seq-map-indexed (lambda (elt idx) (list idx elt)) '(a b c)) ⇒ ((0 a) (b 1) (c 2))

— Function: **seq-mapn**` function &rest sequences`

This function returns the result of applying

functionto each element ofsequences. The arity (see subr-arity) offunctionmust 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

sequencefor whichpredicatereturns 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

sequencefor whichpredicatereturns`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

functionwithinitial-valueand the first element ofsequence, then callingfunctionwith that result and the second element ofsequence, then with that result and the third element ofsequence, etc.functionshould be a function of two arguments. Ifsequenceis empty, this returnsinitial-valuewithout callingfunction.(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 applyingpredicateto each element ofsequencein 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

sequencefor whichpredicatereturns non-`nil`

. If no element matchespredicate, the function returnsdefault.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 applyingpredicateto every element ofsequencereturns non-`nil`

.(seq-every-p #'numberp [2 4 6]) ⇒ t (seq-every-p #'numberp [2 4 "6"]) ⇒ nil

— Function: **seq-empty-p**` sequence`

This function returns non-

`nil`

ifsequenceis empty.(seq-empty-p "not empty") ⇒ nil (seq-empty-p "") ⇒ t

— Function: **seq-count**` predicate sequence`

This function returns the number of elements in

sequencefor whichpredicatereturns 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

sequencethat is sorted according tofunction, a function of two arguments that returns non-`nil`

if the first argument should sort before the second.

— Function: **seq-sort-by**` function predicate sequence`

This function is similar to

`seq-sort`

, but the elements ofsequenceare transformed by applyingfunctionon them before being sorted.functionis a function of one argument.(seq-sort-by #'seq-length #'> ["a" "ab" "abc"]) ⇒ ["abc" "ab" "a"]

— Function: **seq-contains**` sequence elt &optional function`

This function returns the first element in

sequencethat is equal toelt. If the optional argumentfunctionis 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-set-equal-p**` sequence1 sequence2 &optional testfn`

This function checks whether

sequence1andsequence2contain the same elements, regardless of the order. If the optional argumenttestfnis non-`nil`

, it is a function of two arguments to use instead of the default`equal`

.(seq-set-equal-p '(a b c) '(c b a)) ⇒ t (seq-set-equal-p '(a b c) '(c b)) ⇒ nil (seq-set-equal-p '("a" "b" "c") '("c" "b" "a")) ⇒ t (seq-set-equal-p '("a" "b" "c") '("c" "b" "a") #'eq) ⇒ nil

— Function: **seq-position**` sequence elt &optional function`

This function returns the index of the first element in

sequencethat is equal toelt. If the optional argumentfunctionis 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

sequencewith duplicates removed. If the optional argumentfunctionis 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) #'=) ⇒ (1 2)

— Function: **seq-subseq**` sequence start &optional end`

This function returns a subset of

sequencefromstarttoend, both integers (enddefaults to the last element). Ifstartorendis negative, it counts from the end ofsequence.(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

typemade of the concatenation ofsequences.typemay 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 applyingfunctionto each element ofsequence. The result is a sequence of typetype, or a list iftypeis`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

sequencegrouped into sub-sequences of lengthn. The last sequence may contain less elements thann.nmust be an integer. Ifnis 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

sequence1andsequence2. If the optional argumentfunctionis 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

sequence1but not insequence2. If the optional argumentfunctionis 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

sequenceinto an alist whose keys are the result of applyingfunctionto each element ofsequence. 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

sequenceinto a sequence of typetype.typecan 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 ofsequencemust be numbers or markers (see 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 ofsequencemust 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`

(see dolist), except thatsequencecan be a list, vector or string. This is primarily useful for side-effects.

— Macro: **seq-let**` var-sequence val-sequence body...`

This macro binds the variables defined in

var-sequenceto the values that are the corresponding elements ofval-sequence. This is known as destructuring binding. The elements ofvar-sequencecan themselves include sequences, allowing for nested destructuring.The

var-sequencesequence can also include the`&rest`

marker followed by a variable name to be bound to the rest ofval-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]The

`pcase`

patterns provide an alternative facility for destructuring binding, see Destructuring with pcase Patterns.

— Function: **seq-random-elt**` sequence`

This function returns an element of

sequencetaken at random.(seq-random-elt [1 2 3 4]) ⇒ 3 (seq-random-elt [1 2 3 4]) ⇒ 2 (seq-random-elt [1 2 3 4]) ⇒ 4 (seq-random-elt [1 2 3 4]) ⇒ 2 (seq-random-elt [1 2 3 4]) ⇒ 1If

sequenceis empty, this function signals an error.