gnu.org (original) (raw)

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. See alsoseqp 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 thecircular-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 usestring-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: length< sequence length

Return non-nil if sequence is shorter than length. This may be more efficient than computing the length of sequenceif sequence is a long list.

Function: length> sequence length

Return non-nil if sequence is longer than length.

Function: length= sequence length

Return non-nil if the length of sequence is equal tolength.

Function: elt sequence index

This function returns the element of sequence indexed byindex. Legitimate values of index are integers ranging from 0 up to one less than the length of sequence. Ifsequence is a list, out-of-range values behave as fornth. 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], -1

This function generalizes aref (see Functions that Operate on Arrays) andnth (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, ifseqr is 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 to seqr.

Storing a new element into the copy does not affect the originalseqr, 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 Cons Cells and Lists, concat inCreating Strings, and vconcat in Functions for Vectors, for other ways to copy sequences.

(setq bar (list 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 sequenceis 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 (list '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 nreverseback in the same variable which held the original list:

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 (copy-sequence [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 even when they are mutable. See Mutability.

Function: sort sequence &rest keyword-args

This function sorts sequence, which must be a list or vector, and returns a sorted sequence of the same type. The sort is stable, which means that elements with equal sort keys maintain their relative order. It takes the following optional keyword arguments:

:key keyfunc

Use keyfunc, a function that takes a single element fromsequence and returns its key value, to generate the keys used in comparison. If this argument is absent or if keyfunc isnil then identity is assumed; that is, the elements themselves are used as sorting keys.

:lessp predicate

Use predicate to order the keys. predicate is a function that takes two sort keys as arguments and returns non-nil if the first should come before the second. If this argument is absent orpredicate is nil, then value< is used, which is applicable to many different Lisp types and generally sorts in ascending order (see definition of value<, below).

For consistency, any predicate must obey the following rules:

:reverse flag

If flag is non-nil, the sorting order is reversed. With the default :lessp predicate this means sorting in descending order.

:in-place flag

If flag is non-nil, then sequence is sorted in-place (destructively) and returned. If nil, or if this argument is not given, a sorted copy of the input is returned and sequence itself remains unmodified. In-place sorting is slightly faster, but the original sequence is lost.

If the default behavior is not suitable for your needs, it is usually easier and faster to supply a new :key function than a different:lessp predicate. For example, consider sorting these strings:

(setq numbers '("one" "two" "three" "four" "five" "six")) (sort numbers) ⇒ ("five" "four" "one" "six" "three" "two")

You can sort the strings by length instead by supplying a different key function:

(sort numbers :key #'length) ⇒ ("one" "two" "six" "four" "five" "three")

Note how strings of the same length keep their original order, thanks to the sorting stability. Now suppose you want to sort by length, but use the string contents to break ties. The easiest way is to specify a key function that transforms an element to a value that is sorted this way. Since value< orders compound objects (conses, lists, vectors and records) lexicographically, you could do:

(sort numbers :key (lambda (x) (cons (length x) x))) ⇒ ("one" "six" "two" "five" "four" "three")

because (3 . "six") is ordered before (3 . "two") and so on.

For compatibility with previous versions of Emacs, the sortfunction can also be called using the fixed two-argument form:

(sort sequence predicate)

where predicate is the :lessp argument. When using this form, sorting is always done in-place.

See Sorting Text, for more functions that perform sorting. Seedocumentation in Access to Documentation Strings, for a useful example of sort.

Function: value< a b

This function returns non-nil if a comes before b in the standard sorting order; this means that it returns nil whenb comes before a, or if they are equal or unordered.

The arguments a and b must have the same type. Specifically:

Examples:

(value< -4 3.5) ⇒ t (value< "dog" "cat") ⇒ nil (value< 'yip 'yip) ⇒ nil (value< '(3 2) '(3 2 0)) ⇒ t (value< [3 2 "a"] [3 2 "b"]) ⇒ t

Note that nil is treated as either a symbol or an empty list, depending on what it is compared against:

(value< nil '(0)) ⇒ t (value< 'nib nil) ⇒ t

There is no limit to the length of sequences (lists, vectors and so on) that can be compared, but value< may fail with an error if used to compare circular or deeply nested data structures.

The seq.el library provides the following additional sequence manipulation macros and functions, prefixed with seq-.

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 sequence at the specifiedindex, 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(see The setf Macro).

(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 if object is a sequence (a list or array), or any additional type of sequence defined viaseq.el generic functions. This is an extensible variant ofsequencep.

(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 ofsequence. 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-split sequence length

This function returns a list consisting of sub-sequences ofsequence of (at most) length length. (The final element may be shorter than length if the length of sequence isn’t a multiple of length.

(seq-split [0 1 2 3 4] 2) ⇒ ([0 1] [2 3] [4])

Function: seq-do function sequence

This function applies function to each element ofsequence in turn (presumably for side effects), and returnssequence.

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-map-indexed function sequence

This function returns the result of applying function to each element of sequence and its index within seq. The returned value is a list.

(seq-map-indexed (lambda (elt idx) (list idx elt)) '(a b c)) ⇒ ((0 a) (1 b) (2 c))

Function: seq-mapn function &rest sequences

This function returns the result of applying function to each element of sequences. The arity (see subr-arity) 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 sequencefor 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 sequencefor 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-remove-at-position sequence n

This function returns a copy of sequence where the element at (zero-based) index n got removed. The result is a sequence of the same type as sequence.

(seq-remove-at-position [1 -1 3 -3 5] 0) ⇒ [-1 3 -3 5]

(seq-remove-at-position [1 -1 3 -3 5] 3) ⇒ [1 -1 3 5]

Function: seq-keep function sequence

This function returns a list of all non-nil results from calling function on the elements in sequence.

(seq-keep #'cl-digit-char-p '(?6 ?a ?7)) ⇒ (6 7)

Function: seq-reduce function sequence initial-value

This function returns the result of calling function withinitial-value and the first element of sequence, then callingfunction 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.

function is called with two arguments. initial-value(and then the accumulated value) is used as the first argument, and the elements in sequence are used for the second argument.

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 whichpredicate returns non-nil. If no element matchespredicate, 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 predicateto every element of sequence returns 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 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 whichpredicate 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-sort-by function predicate sequence

This function is similar to seq-sort, but the elements ofsequence are transformed by applying function on them before being sorted. function is a function of one argument.

(seq-sort-by #'seq-length #'> ["a" "ab" "abc"]) ⇒ ["abc" "ab" "a"]

Function: seq-contains-p sequence elt &optional function

This function returns non-nil if at least one element insequence is equal to elt. If the optional argumentfunction is non-nil, it is a function of two arguments to use instead of the default equal.

(seq-contains-p '(symbol1 symbol2) 'symbol1) ⇒ t

(seq-contains-p '(symbol1 symbol2) 'symbol3) ⇒ nil

Function: seq-set-equal-p sequence1 sequence2 &optional testfn

This function checks whether sequence1 and sequence2contain the same elements, regardless of the order. If the optional argument testfn is 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 (zero-based) index of the first element insequence that is equal to elt. If the optional argumentfunction 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-positions sequence elt &optional testfn

This function returns a list of the (zero-based) indices of the elements in sequence for which testfn returns non-nil when passed the element and elt as arguments. testfn defaults to equal.

(seq-positions '(a b c a d) 'a) ⇒ (0 3)

(seq-positions '(a b c a d) 'z) ⇒ nil

(seq-positions '(11 5 7 12 9 15) 10 #'>=) ⇒ (0 3 5)

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) #'=) ⇒ (1 2)

Function: seq-subseq sequence start &optional end

This function returns a subset of sequence from startto end, both integers (end defaults to the last element). If start or end is 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 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-concatenateto the result of applying function to each element ofsequence. 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 sequencegrouped into sub-sequences of length n. The last sequence may contain less elements than n. n must be an integer. Ifn 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-union sequence1 sequence2 &optional function

This function returns a list of the elements that appear either insequence1 or sequence2. The elements of the returned list are all unique, in the sense that no two elements there will compare equal. If the optional argument function is non-nil, it should be a function of two arguments to use to compare elements, instead of the default equal.

(seq-union [1 2 3] [3 5]) ⇒ (1 2 3 5)

Function: seq-intersection sequence1 sequence2 &optional function

This function returns a list of the elements that appear both insequence1 and sequence2. If the optional argumentfunction 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 insequence1 but not in sequence2. If the optional argumentfunction 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 (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 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 (see dolist), except that sequence can 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-sequence to the values that are the corresponding elements of val-sequence. This is known as destructuring binding. The elements ofvar-sequence can themselves include sequences, allowing for nested destructuring.

The var-sequence sequence can also include the &restmarker 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.

Macro: seq-setq var-sequence val-sequence

This macro works similarly to seq-let, except that values are assigned to variables as if by setq instead of as in alet binding.

(let ((a nil) (b nil)) (seq-setq (_ a _ b) '(1 2 3 4)) (list a b)) ⇒ (2 4)

Function: seq-random-elt sequence

This function returns an element of sequence taken 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]) ⇒ 1

If sequence is empty, this function signals an error.