The sequence type is the union of two other Lisp types: lists and arrays. In other words, any list is a sequence, and any array is a sequence. The common property that all sequences have is that each is an ordered collection of elements.
An array is a fixed-length object with a slot for each of its elements. All the elements are accessible in constant time. The four types of arrays are strings, vectors, char-tables and bool-vectors.
A list is a sequence of elements, but it is not a single primitive object; it is made of cons cells, one cell per element. Finding the nth element requires looking through n cons cells, so elements farther from the beginning of the list take longer to access. But it is possible to add elements to the list, or remove elements.
The following diagram shows the relationship between these types:
_____________________________________________
| |
| Sequence |
| ______ ________________________________ |
| | | | | |
| | List | | Array | |
| | | | ________ ________ | |
| |______| | | | | | | |
| | | Vector | | String | | |
| | |________| |________| | |
| | ____________ _____________ | |
| | | | | | | |
| | | Char-table | | Bool-vector | | |
| | |____________| |_____________| | |
| |________________________________| |
|_____________________________________________|
This section describes functions that accept any kind of sequence.
This function returns t if object is a list, vector,
string, bool-vector, or char-table, nil otherwise. See also
seqp below.
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.
Return non-nil if sequence is shorter than length.
This may be more efficient than computing the length of sequence
if sequence is a long list.
Return non-nil if sequence is longer than length.
Return non-nil if the length of sequence is equal to
length.
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. 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) and
nth (see Definition of nth).
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, if seqr 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 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 Cons Cells and Lists, concat in
Creating 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)]
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"
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 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 (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.
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 keyfuncUse keyfunc, a function that takes a single element from
sequence and returns its key value, to generate the keys used in
comparison. If this argument is absent or if keyfunc is
nil then identity is assumed; that is, the elements
themselves are used as sorting keys.
:lessp predicateUse 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 or
predicate 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 flagIf flag is non-nil, the sorting order is reversed. With
the default :lessp predicate this means sorting in descending order.
:in-place flagIf 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 sort
function 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. See
documentation in Access to Documentation Strings, for a useful
example of sort.
This function returns non-nil if a comes before b in
the standard sorting order; this means that it returns nil when
b comes before a, or if they are equal or unordered.
The arguments a and b must have the same type. Specifically:
< (see definition of <).
string-lessp (see definition of string-lessp) and symbols are compared by comparing their names as
strings.
value< on
the first pair of differing elements. If one sequence runs out of
elements before the other, the shorter sequence comes before the longer.
nil) will compare before any live
buffer.
nil.
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.
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
(see The setf Macro).
(setq vec [1 2 3 4]) (setf (seq-elt vec 2) 5) vec ⇒ [1 2 5 4]
This function returns the number of elements in sequence. For
built-in sequence types, seq-length behaves like length.
See Definition of length.
This function returns non-nil if object is a sequence
(a list or array), or any additional type of sequence defined via
seq.el generic functions. This is an extensible variant of
sequencep.
(seqp [1 2]) ⇒ t
(seqp 2) ⇒ nil
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"
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) ⇒ []
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]) ⇒ []
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]
This function returns a list consisting of sub-sequences of sequence 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])
This function applies function to each element of sequence in turn (presumably for side effects), and returns 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")
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))
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")
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
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
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]
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)
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.
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
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
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
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-every-p #'numberp [2 4 "6"]) ⇒ nil
This function returns non-nil if sequence is empty.
(seq-empty-p "not empty") ⇒ nil
(seq-empty-p "") ⇒ t
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
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.
This function is similar to seq-sort, but the elements of
sequence 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"]
This function returns non-nil if at least one element in
sequence 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-p '(symbol1 symbol2) 'symbol1) ⇒ t
(seq-contains-p '(symbol1 symbol2) 'symbol3) ⇒ nil
This function checks whether sequence1 and sequence2
contain 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
This function returns the (zero-based) 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
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)
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)
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]
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"
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)
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))
This function returns a list of the elements that appear either in
sequence1 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)
This function returns a copy of sequence1 from which the
elements that do not appear in sequence2 were removed. 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)
This function returns a copy of sequence1 from which the
elements that appear in sequence2 were removed. 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)
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)))
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]
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
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
This macro is like dolist (see dolist), except
that sequence can be a list, vector or string. This is
primarily useful for side-effects.
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 of var-sequence can themselves include sequences, allowing for nested destructuring.
The var-sequence sequence can also include the &rest
marker followed by a variable name to be bound to the rest of
val-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.
This macro works similarly to seq-let, except that values are
assigned to variables as if by setq instead of as in a
let binding.
(let ((a nil)
(b nil))
(seq-setq (_ a _ b) '(1 2 3 4))
(list a b))
⇒ (2 4)
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.
An array object has slots that hold a number of other Lisp objects, called the elements of the array. Any element of an array may be accessed in constant time. In contrast, the time to access an element of a list is proportional to the position of that element in the list.
Emacs defines four types of array, all one-dimensional:
strings (see String Type), vectors (see Vector Type), bool-vectors (see Bool-Vector Type), and
char-tables (see Char-Table Type). Vectors and char-tables
can hold elements of any type, but strings can only hold characters,
and bool-vectors can only hold t and nil.
All four kinds of array share these characteristics:
aref and aset, respectively (see Functions that Operate on Arrays).
When you create an array, other than a char-table, you must specify its length. You cannot specify the length of a char-table, because that is determined by the range of character codes.
In principle, if you want an array of text characters, you could use either a string or a vector. In practice, we always choose strings for such applications, for four reasons:
By contrast, for an array of keyboard input characters (such as a key sequence), a vector may be necessary, because many keyboard input characters are outside the range that will fit in a string. See Key Sequence Input.
In this section, we describe the functions that accept all types of arrays.
This function returns t if object is an array (i.e., a
vector, a string, a bool-vector or a char-table).
(arrayp [a])
⇒ t
(arrayp "asdf")
⇒ t
(arrayp (syntax-table)) ;; A char-table.
⇒ t
This function returns the indexth element of the array or record arr. The first element is at index zero.
(setq primes [2 3 5 7 11 13])
⇒ [2 3 5 7 11 13]
(aref primes 4)
⇒ 11
(aref "abcdefg" 1)
⇒ 98 ; ‘b’ is ASCII code 98.
See also the function elt, in Sequences.
This function sets the indexth element of array to be object. It returns object.
(setq w (vector 'foo 'bar 'baz))
⇒ [foo bar baz]
(aset w 0 'fu)
⇒ fu
w
⇒ [fu bar baz]
;; copy-sequence copies the string to be modified later.
(setq x (copy-sequence "asdfasfd"))
⇒ "asdfasfd"
(aset x 3 ?Z)
⇒ 90
x
⇒ "asdZasfd"
The array should be mutable. See Mutability.
If array is a string and object is not a character, a
wrong-type-argument error results. For more information about
string mutation, see Modifying Strings.
This function fills the array array with object, so that each element of array is object. It returns array.
(setq a (copy-sequence [a b c d e f g]))
⇒ [a b c d e f g]
(fillarray a 0)
⇒ [0 0 0 0 0 0 0]
a
⇒ [0 0 0 0 0 0 0]
(setq s (copy-sequence "When in the course"))
⇒ "When in the course"
(fillarray s ?-)
⇒ "------------------"
If array is a string and object is not a character, a
wrong-type-argument error results.
The general sequence functions copy-sequence and length
are often useful for objects known to be arrays. See Sequences.
A vector is a general-purpose array whose elements can be any Lisp objects. (By contrast, the elements of a string can only be characters. See Strings and Characters.) Vectors are used in Emacs for many purposes: as key sequences (see Key Sequences), as symbol-lookup tables (see Creating and Interning Symbols), as part of the representation of a byte-compiled function (see Byte Compilation), and more.
Like other arrays, vectors use zero-origin indexing: the first element has index 0.
Vectors are printed with square brackets surrounding the elements.
Thus, a vector whose elements are the symbols a, b and
a is printed as [a b a]. You can write vectors in the
same way in Lisp input.
A vector, like a string or a number, is considered a constant for
evaluation: the result of evaluating it is the same vector. This does
not evaluate or even examine the elements of the vector.
See Self-Evaluating Forms. Vectors written with square brackets
should not be modified via aset or other destructive
operations. See Mutability.
Here are examples illustrating these principles:
(setq avector [1 two '(three) "four" [five]])
⇒ [1 two '(three) "four" [five]]
(eval avector)
⇒ [1 two '(three) "four" [five]]
(eq avector (eval avector))
⇒ t
Here are some functions that relate to vectors:
This function returns t if object is a vector.
(vectorp [a])
⇒ t
(vectorp "asdf")
⇒ nil
This function creates and returns a vector whose elements are the arguments, objects.
(vector 'foo 23 [bar baz] "rats")
⇒ [foo 23 [bar baz] "rats"]
(vector)
⇒ []
This function returns a new vector consisting of length elements, each initialized to object.
(setq sleepy (make-vector 9 'Z))
⇒ [Z Z Z Z Z Z Z Z Z]
This function returns a new vector containing all the elements of sequences. The arguments sequences may be proper lists, vectors, strings or bool-vectors. If no sequences are given, the empty vector is returned.
The value is either the empty vector, or is a newly constructed
nonempty vector that is not eq to any existing vector.
(setq a (vconcat '(A B C) '(D E F)))
⇒ [A B C D E F]
(eq a (vconcat a))
⇒ nil
(vconcat)
⇒ []
(vconcat [A B C] "aa" '(foo (6 7)))
⇒ [A B C 97 97 foo (6 7)]
The vconcat function also allows byte-code function objects as
arguments. This is a special feature to make it easy to access the entire
contents of a byte-code function object. See Closure Function Objects.
For other concatenation functions, see mapconcat in Mapping Functions, concat in Creating Strings, and append
in Building Cons Cells and Lists.
The append function also provides a way to convert a vector into a
list with the same elements:
(setq avector [1 two (quote (three)) "four" [five]])
⇒ [1 two '(three) "four" [five]]
(append avector nil)
⇒ (1 two '(three) "four" [five])
A char-table is much like a vector, except that it is indexed by
character codes. Any valid character code, without modifiers, can be
used as an index in a char-table. You can access a char-table’s
elements with aref and aset, as with any array. In
addition, a char-table can have extra slots to hold additional
data not associated with particular character codes. Like vectors,
char-tables are constants when evaluated, and can hold elements of any
type.
Each char-table has a subtype, a symbol, which serves two purposes:
display-table
as the subtype, and syntax tables are char-tables with
syntax-table as the subtype. The subtype can be queried using
the function char-table-subtype, described below.
char-table-extra-slots symbol property (see Symbol Properties), whose value should be an integer between 0 and 10. If
the subtype has no such symbol property, the char-table has no extra
slots.
A char-table can have a parent, which is another char-table. If
it does, then whenever the char-table specifies nil for a
particular character c, it inherits the value specified in the
parent. In other words, (aref char-table c) returns
the value from the parent of char-table if char-table itself
specifies nil.
A char-table can also have a default value. If so, then
(aref char-table c) returns the default value
whenever the char-table does not specify any other non-nil value.
Return a newly-created char-table, with subtype subtype (a
symbol). Each element is initialized to init, which defaults to
nil. You cannot alter the subtype of a char-table after the
char-table is created.
There is no argument to specify the length of the char-table, because all char-tables have room for any valid character code as an index.
If subtype has the char-table-extra-slots symbol
property, that specifies the number of extra slots in the char-table.
This should be an integer between 0 and 10; otherwise,
make-char-table raises an error. If subtype has no
char-table-extra-slots symbol property (see Property Lists), the char-table has no extra slots.
This function returns t if object is a char-table, and
nil otherwise.
This function returns the subtype symbol of char-table.
There is no special function to access default values in a char-table.
To do that, use char-table-range (see below).
This function returns the parent of char-table. The parent is
always either nil or another char-table.
This function sets the parent of char-table to new-parent.
This function returns the contents of extra slot n (zero based) of char-table. The number of extra slots in a char-table is determined by its subtype.
This function stores value in extra slot n (zero based) of char-table.
A char-table can specify an element value for a single character code; it can also specify a value for an entire character set.
This returns the value specified in char-table for a range of characters range. Here are the possibilities for range:
nilRefers to the default value.
Refers to the element for character char (supposing char is a valid character code).
(from . to)A cons cell refers to all the characters in the inclusive range ‘[from..to]’. In this case, the function returns the value for the character specified by from.
This function sets the value in char-table for a range of characters range. Here are the possibilities for range:
nilRefers to the default value.
tRefers to the whole range of character codes.
Refers to the element for character char (supposing char is a valid character code).
(from . to)A cons cell refers to all the characters in the inclusive range ‘[from..to]’.
This function calls its argument function for each element of
char-table that has a non-nil value. The call to
function is with two arguments, a key and a value. The key
is a possible range argument for char-table-range—either
a valid character or a cons cell (from . to),
specifying a range of characters that share the same value. The value is
what (char-table-range char-table key) returns.
Overall, the key-value pairs passed to function describe all the values stored in char-table.
The return value is always nil; to make calls to
map-char-table useful, function should have side effects.
For example, here is how to examine the elements of the syntax table:
(let (accumulator)
(map-char-table
(lambda (key value)
(setq accumulator
(cons (list
(if (consp key)
(list (car key) (cdr key))
key)
value)
accumulator)))
(syntax-table))
accumulator)
⇒
(((2597602 4194303) (2)) ((2597523 2597601) (3))
... (65379 (5 . 65378)) (65378 (4 . 65379)) (65377 (1))
... (12 (0)) (11 (3)) (10 (12)) (9 (0)) ((0 8) (3)))
A bool-vector is much like a vector, except that it stores only the
values t and nil. If you try to store any non-nil
value into an element of the bool-vector, the effect is to store
t there. As with all arrays, bool-vector indices start from 0,
and the length cannot be changed once the bool-vector is created.
Bool-vectors are constants when evaluated.
Several functions work specifically with bool-vectors; aside from that, you manipulate them with same functions used for other kinds of arrays.
Return a new bool-vector of length elements, each one initialized to initial.
This function creates and returns a bool-vector whose elements are the arguments, objects.
This returns t if object is a bool-vector,
and nil otherwise.
There are also some bool-vector set operation functions, described below:
Return bitwise exclusive or of bool vectors a and b. If optional argument c is given, the result of this operation is stored into c. All arguments should be bool vectors of the same length.
Return bitwise or of bool vectors a and b. If optional argument c is given, the result of this operation is stored into c. All arguments should be bool vectors of the same length.
Return bitwise and of bool vectors a and b. If optional argument c is given, the result of this operation is stored into c. All arguments should be bool vectors of the same length.
Return set difference of bool vectors a and b. If optional argument c is given, the result of this operation is stored into c. All arguments should be bool vectors of the same length.
Return set complement of bool vector a. If optional argument b is given, the result of this operation is stored into b. All arguments should be bool vectors of the same length.
Return t if every t value in a is also t in
b, nil otherwise. All arguments should be bool vectors of the
same length.
Return the number of consecutive elements in a equal b
starting at i. a is a bool vector, b is t
or nil, and i is an index into a.
Return the number of elements that are t in bool vector a.
The printed form represents up to 8 boolean values as a single character:
(bool-vector t nil t nil)
⇒ #&4"^E"
(bool-vector)
⇒ #&0""
You can use vconcat to print a bool-vector like other vectors:
(vconcat (bool-vector nil t nil t))
⇒ [nil t nil t]
Here is another example of creating, examining, and updating a bool-vector:
(setq bv (make-bool-vector 5 t))
⇒ #&5"^_"
(aref bv 1)
⇒ t
(aset bv 3 nil)
⇒ nil
bv
⇒ #&5"^W"
These results make sense because the binary codes for control-_ and control-W are 11111 and 10111, respectively.
A ring is a fixed-size data structure that supports insertion,
deletion, rotation, and modulo-indexed reference and traversal. An
efficient ring data structure is implemented by the ring
package. It provides the functions listed in this section.
Note that several rings in Emacs, like the kill ring and the
mark ring, are actually implemented as simple lists, not using
the ring package; thus the following functions won’t work on
them.
This returns a new ring capable of holding size objects. size should be an integer.
This returns t if object is a ring, nil otherwise.
This returns the maximum capacity of the ring.
This returns the number of objects that ring currently contains.
The value will never exceed that returned by ring-size.
This returns a list of the objects in ring, in order, newest first.
This returns a new ring which is a copy of ring.
The new ring contains the same (eq) objects as ring.
This returns t if ring is empty, nil otherwise.
The newest element in the ring always has index 0. Higher indices correspond to older elements. Indices are computed modulo the ring length. Index −1 corresponds to the oldest element, −2 to the next-oldest, and so forth.
This returns the object in ring found at index index.
index may be negative or greater than the ring length. If
ring is empty, ring-ref signals an error.
This inserts object into ring, making it the newest element, and returns object.
If the ring is full, insertion removes the oldest element to make room for the new element.
Remove an object from ring, and return that object. The
argument index specifies which item to remove; if it is
nil, that means to remove the oldest item. If ring is
empty, ring-remove signals an error.
This inserts object into ring, treating it as the oldest element. The return value is not significant.
If the ring is full, this function removes the newest element to make room for the inserted element.
Set the size of ring to size. If the new size is smaller, then the oldest items in the ring are discarded.
If you are careful not to exceed the ring size, you can use the ring as a first-in-first-out queue. For example:
(let ((fifo (make-ring 5)))
(mapc (lambda (obj) (ring-insert fifo obj))
'(0 one "two"))
(list (ring-remove fifo) t
(ring-remove fifo) t
(ring-remove fifo)))
⇒ (0 t one t "two")