mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-15 09:47:20 +00:00
1705 lines
48 KiB
Plaintext
1705 lines
48 KiB
Plaintext
@c -*-texinfo-*-
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
|
@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
|
|
@c Foundation, Inc.
|
|
@c See the file elisp.texi for copying conditions.
|
|
@node Sequences Arrays Vectors
|
|
@chapter Sequences, Arrays, and Vectors
|
|
@cindex sequence
|
|
|
|
The @dfn{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 @dfn{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
|
|
@var{n}th element requires looking through @var{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:
|
|
|
|
@example
|
|
@group
|
|
_____________________________________________
|
|
| |
|
|
| Sequence |
|
|
| ______ ________________________________ |
|
|
| | | | | |
|
|
| | List | | Array | |
|
|
| | | | ________ ________ | |
|
|
| |______| | | | | | | |
|
|
| | | Vector | | String | | |
|
|
| | |________| |________| | |
|
|
| | ____________ _____________ | |
|
|
| | | | | | | |
|
|
| | | Char-table | | Bool-vector | | |
|
|
| | |____________| |_____________| | |
|
|
| |________________________________| |
|
|
|_____________________________________________|
|
|
@end group
|
|
@end example
|
|
|
|
@menu
|
|
* Sequence Functions:: Functions that accept any kind of sequence.
|
|
* Arrays:: Characteristics of arrays in Emacs Lisp.
|
|
* Array Functions:: Functions specifically for arrays.
|
|
* Vectors:: Special characteristics of Emacs Lisp vectors.
|
|
* Vector Functions:: Functions specifically for vectors.
|
|
* Char-Tables:: How to work with char-tables.
|
|
* Bool-Vectors:: How to work with bool-vectors.
|
|
* Rings:: Managing a fixed-size ring of objects.
|
|
@end menu
|
|
|
|
@node Sequence Functions
|
|
@section Sequences
|
|
|
|
This section describes functions that accept any kind of sequence.
|
|
|
|
@defun sequencep object
|
|
This function returns @code{t} if @var{object} is a list, vector,
|
|
string, bool-vector, or char-table, @code{nil} otherwise.
|
|
@end defun
|
|
|
|
@defun length sequence
|
|
@cindex string length
|
|
@cindex list length
|
|
@cindex vector length
|
|
@cindex sequence length
|
|
@cindex char-table length
|
|
@anchor{Definition of length}
|
|
This function returns the number of elements in @var{sequence}. If
|
|
@var{sequence} is a dotted list, a @code{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.
|
|
|
|
@xref{Definition of safe-length}, for the related function @code{safe-length}.
|
|
|
|
@example
|
|
@group
|
|
(length '(1 2 3))
|
|
@result{} 3
|
|
@end group
|
|
@group
|
|
(length ())
|
|
@result{} 0
|
|
@end group
|
|
@group
|
|
(length "foobar")
|
|
@result{} 6
|
|
@end group
|
|
@group
|
|
(length [1 2 3])
|
|
@result{} 3
|
|
@end group
|
|
@group
|
|
(length (make-bool-vector 5 nil))
|
|
@result{} 5
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@noindent
|
|
See also @code{string-bytes}, in @ref{Text Representations}.
|
|
|
|
If you need to compute the width of a string on display, you should use
|
|
@code{string-width} (@pxref{Size of Displayed Text}), not @code{length},
|
|
since @code{length} only counts the number of characters, but does not
|
|
account for the display width of each character.
|
|
|
|
@defun elt sequence index
|
|
@anchor{Definition of elt}
|
|
@cindex elements of sequences
|
|
This function returns the element of @var{sequence} indexed by
|
|
@var{index}. Legitimate values of @var{index} are integers ranging
|
|
from 0 up to one less than the length of @var{sequence}. If
|
|
@var{sequence} is a list, out-of-range values behave as for
|
|
@code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values
|
|
trigger an @code{args-out-of-range} error.
|
|
|
|
@example
|
|
@group
|
|
(elt [1 2 3 4] 2)
|
|
@result{} 3
|
|
@end group
|
|
@group
|
|
(elt '(1 2 3 4) 2)
|
|
@result{} 3
|
|
@end group
|
|
@group
|
|
;; @r{We use @code{string} to show clearly which character @code{elt} returns.}
|
|
(string (elt "1234" 2))
|
|
@result{} "3"
|
|
@end group
|
|
@group
|
|
(elt [1 2 3 4] 4)
|
|
@error{} Args out of range: [1 2 3 4], 4
|
|
@end group
|
|
@group
|
|
(elt [1 2 3 4] -1)
|
|
@error{} Args out of range: [1 2 3 4], -1
|
|
@end group
|
|
@end example
|
|
|
|
This function generalizes @code{aref} (@pxref{Array Functions}) and
|
|
@code{nth} (@pxref{Definition of nth}).
|
|
@end defun
|
|
|
|
@defun copy-sequence sequence
|
|
@cindex copying sequences
|
|
This function returns a copy of @var{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
|
|
@var{sequence}, and vice versa. However, the elements of the new
|
|
sequence are not copies; they are identical (@code{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.
|
|
@xref{Text Properties}.
|
|
|
|
This function does not work for dotted lists. Trying to copy a
|
|
circular list may cause an infinite loop.
|
|
|
|
See also @code{append} in @ref{Building Lists}, @code{concat} in
|
|
@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions},
|
|
for other ways to copy sequences.
|
|
|
|
@example
|
|
@group
|
|
(setq bar '(1 2))
|
|
@result{} (1 2)
|
|
@end group
|
|
@group
|
|
(setq x (vector 'foo bar))
|
|
@result{} [foo (1 2)]
|
|
@end group
|
|
@group
|
|
(setq y (copy-sequence x))
|
|
@result{} [foo (1 2)]
|
|
@end group
|
|
|
|
@group
|
|
(eq x y)
|
|
@result{} nil
|
|
@end group
|
|
@group
|
|
(equal x y)
|
|
@result{} t
|
|
@end group
|
|
@group
|
|
(eq (elt x 1) (elt y 1))
|
|
@result{} t
|
|
@end group
|
|
|
|
@group
|
|
;; @r{Replacing an element of one sequence.}
|
|
(aset x 0 'quux)
|
|
x @result{} [quux (1 2)]
|
|
y @result{} [foo (1 2)]
|
|
@end group
|
|
|
|
@group
|
|
;; @r{Modifying the inside of a shared element.}
|
|
(setcar (aref x 1) 69)
|
|
x @result{} [quux (69 2)]
|
|
y @result{} [foo (69 2)]
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun reverse sequence
|
|
@cindex string reverse
|
|
@cindex list reverse
|
|
@cindex vector reverse
|
|
@cindex sequence reverse
|
|
This function creates a new sequence whose elements are the elements
|
|
of @var{sequence}, but in reverse order. The original argument @var{sequence}
|
|
is @emph{not} altered. Note that char-tables cannot be reversed.
|
|
|
|
@example
|
|
@group
|
|
(setq x '(1 2 3 4))
|
|
@result{} (1 2 3 4)
|
|
@end group
|
|
@group
|
|
(reverse x)
|
|
@result{} (4 3 2 1)
|
|
x
|
|
@result{} (1 2 3 4)
|
|
@end group
|
|
@group
|
|
(setq x [1 2 3 4])
|
|
@result{} [1 2 3 4]
|
|
@end group
|
|
@group
|
|
(reverse x)
|
|
@result{} [4 3 2 1]
|
|
x
|
|
@result{} [1 2 3 4]
|
|
@end group
|
|
@group
|
|
(setq x "xyzzy")
|
|
@result{} "xyzzy"
|
|
@end group
|
|
@group
|
|
(reverse x)
|
|
@result{} "yzzyx"
|
|
x
|
|
@result{} "xyzzy"
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun nreverse sequence
|
|
@cindex reversing a string
|
|
@cindex reversing a list
|
|
@cindex reversing a vector
|
|
This function reverses the order of the elements of @var{sequence}.
|
|
Unlike @code{reverse} the original @var{sequence} may be modified.
|
|
|
|
For example:
|
|
|
|
@example
|
|
@group
|
|
(setq x '(a b c))
|
|
@result{} (a b c)
|
|
@end group
|
|
@group
|
|
x
|
|
@result{} (a b c)
|
|
(nreverse x)
|
|
@result{} (c b a)
|
|
@end group
|
|
@group
|
|
;; @r{The cons cell that was first is now last.}
|
|
x
|
|
@result{} (a)
|
|
@end group
|
|
@end example
|
|
|
|
To avoid confusion, we usually store the result of @code{nreverse}
|
|
back in the same variable which held the original list:
|
|
|
|
@example
|
|
(setq x (nreverse x))
|
|
@end example
|
|
|
|
Here is the @code{nreverse} of our favorite example, @code{(a b c)},
|
|
presented graphically:
|
|
|
|
@smallexample
|
|
@group
|
|
@r{Original list head:} @r{Reversed list:}
|
|
------------- ------------- ------------
|
|
| car | cdr | | car | cdr | | car | cdr |
|
|
| a | nil |<-- | b | o |<-- | c | o |
|
|
| | | | | | | | | | | | |
|
|
------------- | --------- | - | -------- | -
|
|
| | | |
|
|
------------- ------------
|
|
@end group
|
|
@end smallexample
|
|
|
|
For the vector, it is even simpler because you don't need setq:
|
|
|
|
@example
|
|
(setq x [1 2 3 4])
|
|
@result{} [1 2 3 4]
|
|
(nreverse x)
|
|
@result{} [4 3 2 1]
|
|
x
|
|
@result{} [4 3 2 1]
|
|
@end example
|
|
|
|
Note that unlike @code{reverse}, this function doesn't work with strings.
|
|
Although you can alter string data by using @code{aset}, it is strongly
|
|
encouraged to treat strings as immutable.
|
|
|
|
@end defun
|
|
|
|
@defun sort sequence predicate
|
|
@cindex stable sort
|
|
@cindex sorting lists
|
|
@cindex sorting vectors
|
|
This function sorts @var{sequence} stably. Note that this function doesn't work
|
|
for all sequences; it may be used only for lists and vectors. If @var{sequence}
|
|
is a list, it is modified destructively. This functions returns the sorted
|
|
@var{sequence} and compares elements using @var{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 @var{predicate} must be a function that accepts two
|
|
arguments. It is called with two elements of @var{sequence}. To get an
|
|
increasing order sort, the @var{predicate} should return non-@code{nil} if the
|
|
first element is ``less'' than the second, or @code{nil} if not.
|
|
|
|
The comparison function @var{predicate} must give reliable results for
|
|
any given pair of arguments, at least within a single call to
|
|
@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is
|
|
less than @var{b}, @var{b} must not be less than @var{a}. It must be
|
|
@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
|
|
is less than @var{c}, then @var{a} must be less than @var{c}. If you
|
|
use a comparison function which does not meet these requirements, the
|
|
result of @code{sort} is unpredictable.
|
|
|
|
The destructive aspect of @code{sort} for lists is that it rearranges the
|
|
cons cells forming @var{sequence} by changing @sc{cdr}s. 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 @code{copy-sequence} and then sort.
|
|
|
|
Sorting does not change the @sc{car}s of the cons cells in @var{sequence};
|
|
the cons cell that originally contained the element @code{a} in
|
|
@var{sequence} still has @code{a} in its @sc{car} after sorting, but it now
|
|
appears in a different position in the list due to the change of
|
|
@sc{cdr}s. For example:
|
|
|
|
@example
|
|
@group
|
|
(setq nums '(1 3 2 6 5 4 0))
|
|
@result{} (1 3 2 6 5 4 0)
|
|
@end group
|
|
@group
|
|
(sort nums '<)
|
|
@result{} (0 1 2 3 4 5 6)
|
|
@end group
|
|
@group
|
|
nums
|
|
@result{} (1 2 3 4 5 6)
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
@strong{Warning}: Note that the list in @code{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 @code{sort} and use that. Most often we store the result back into
|
|
the variable that held the original list:
|
|
|
|
@example
|
|
(setq nums (sort nums '<))
|
|
@end example
|
|
|
|
For the better understanding of what stable sort is, consider the following
|
|
vector example. After sorting, all items whose @code{car} is 8 are grouped
|
|
at the beginning of @code{vector}, but their relative order is preserved.
|
|
All items whose @code{car} is 9 are grouped at the end of @code{vector},
|
|
but their relative order is also preserved:
|
|
|
|
@example
|
|
@group
|
|
(setq
|
|
vector
|
|
(vector '(8 . "xxx") '(9 . "aaa") '(8 . "bbb") '(9 . "zzz")
|
|
'(9 . "ppp") '(8 . "ttt") '(8 . "eee") '(9 . "fff")))
|
|
@result{} [(8 . "xxx") (9 . "aaa") (8 . "bbb") (9 . "zzz")
|
|
(9 . "ppp") (8 . "ttt") (8 . "eee") (9 . "fff")]
|
|
@end group
|
|
@group
|
|
(sort vector (lambda (x y) (< (car x) (car y))))
|
|
@result{} [(8 . "xxx") (8 . "bbb") (8 . "ttt") (8 . "eee")
|
|
(9 . "aaa") (9 . "zzz") (9 . "ppp") (9 . "fff")]
|
|
@end group
|
|
@end example
|
|
|
|
@xref{Sorting}, for more functions that perform sorting.
|
|
See @code{documentation} in @ref{Accessing Documentation}, for a
|
|
useful example of @code{sort}.
|
|
@end defun
|
|
|
|
@cindex sequence functions in seq
|
|
@cindex seq library
|
|
The @file{seq.el} library provides the following additional sequence
|
|
manipulation macros and functions, prefixed with @code{seq-}. To use
|
|
them, you must first load the @file{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 @file{seq.el} library can be extended to work with additional
|
|
types of sequential data-structures. For that purpose, all functions
|
|
are defined using @code{cl-defgeneric}.
|
|
|
|
@defun seq-elt sequence index
|
|
This function the element at the index @var{index} in
|
|
@var{sequence}. @var{index} can be an integer from zero up to the
|
|
length of @var{sequence} minus one. For out-of-range values on
|
|
built-in sequence types, @code{seq-elt} behaves like @code{elt}.
|
|
@xref{Definition of elt}.
|
|
|
|
@example
|
|
@group
|
|
(seq-elt [1 2 3 4] 2)
|
|
@result{} 3
|
|
@end group
|
|
|
|
@code{seq-elt} returns settable places using @code{setf}.
|
|
|
|
@group
|
|
(setq vec [1 2 3 4])
|
|
(setf (seq-elt vec 2) 5)
|
|
vec
|
|
@result{} [1 2 5 4]
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-length sequence
|
|
This function returns the number of elements in @var{sequence}. For
|
|
built-in sequence types, @code{seq-length} behaves like @code{length}.
|
|
@xref{Definition of length}.
|
|
@end defun
|
|
|
|
@defun seqp sequence
|
|
This function returns non-@code{nil} if @var{sequence} is a sequence
|
|
(a list or array), or any additional type of sequence defined via
|
|
@file{seq.el} generic functions.
|
|
|
|
@example
|
|
@group
|
|
(seqp [1 2])
|
|
@result{} t
|
|
@end group
|
|
@group
|
|
(seqp 2)
|
|
@result{} nil
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-drop sequence n
|
|
This function returns all but the first @var{n} (an integer)
|
|
elements of @var{sequence}. If @var{n} is negative or zero,
|
|
the result is @var{sequence}.
|
|
|
|
@example
|
|
@group
|
|
(seq-drop [1 2 3 4 5 6] 3)
|
|
@result{} [4 5 6]
|
|
@end group
|
|
@group
|
|
(seq-drop "hello world" -4)
|
|
@result{} "hello world"
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-take sequence n
|
|
This function returns the first @var{n} (an integer) elements of
|
|
@var{sequence}. If @var{n} is negative or zero, the result
|
|
is @code{nil}.
|
|
|
|
@example
|
|
@group
|
|
(seq-take '(1 2 3 4) 3)
|
|
@result{} (1 2 3)
|
|
@end group
|
|
@group
|
|
(seq-take [1 2 3 4] 0)
|
|
@result{} []
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-take-while predicate sequence
|
|
This function returns the members of @var{sequence} in order,
|
|
stopping before the first one for which @var{predicate} returns @code{nil}.
|
|
|
|
@example
|
|
@group
|
|
(seq-take-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
|
|
@result{} (1 2 3)
|
|
@end group
|
|
@group
|
|
(seq-take-while (lambda (elt) (> elt 0)) [-1 4 6])
|
|
@result{} []
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-drop-while predicate sequence
|
|
This function returns the members of @var{sequence} in order,
|
|
starting from the first one for which @var{predicate} returns @code{nil}.
|
|
|
|
@example
|
|
@group
|
|
(seq-drop-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
|
|
@result{} (-1 -2)
|
|
@end group
|
|
@group
|
|
(seq-drop-while (lambda (elt) (< elt 0)) [1 4 6])
|
|
@result{} [1 4 6]
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-do function sequence
|
|
This function applies @var{function} to each element of
|
|
@var{sequence} in turn (presumably for side effects) and returns
|
|
@var{sequence}.
|
|
@end defun
|
|
|
|
@defun seq-map function sequence
|
|
This function returns the result of applying @var{function} to each
|
|
element of @var{sequence}. The returned value is a list.
|
|
|
|
@example
|
|
@group
|
|
(seq-map #'1+ '(2 4 6))
|
|
@result{} (3 5 7)
|
|
@end group
|
|
@group
|
|
(seq-map #'symbol-name [foo bar])
|
|
@result{} ("foo" "bar")
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-map-indexed function sequence
|
|
This function returns the result of applying @var{function} to each
|
|
element of @var{sequence} and its index within @var{seq}. The
|
|
returned value is a list.
|
|
|
|
@example
|
|
@group
|
|
(seq-map-indexed (lambda (elt idx)
|
|
(list idx elt))
|
|
'(a b c))
|
|
@result{} ((0 a) (b 1) (c 2))
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-mapn function &rest sequences
|
|
This function returns the result of applying @var{function} to each
|
|
element of @var{sequences}. The arity of @var{function} must match
|
|
the number of sequences. Mapping stops at the shortest sequence, and
|
|
the returned value is a list.
|
|
|
|
@example
|
|
@group
|
|
(seq-mapn #'+ '(2 4 6) '(20 40 60))
|
|
@result{} (22 44 66)
|
|
@end group
|
|
@group
|
|
(seq-mapn #'concat '("moskito" "bite") ["bee" "sting"])
|
|
@result{} ("moskitobee" "bitesting")
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-filter predicate sequence
|
|
@cindex filtering sequences
|
|
This function returns a list of all the elements in @var{sequence}
|
|
for which @var{predicate} returns non-@code{nil}.
|
|
|
|
@example
|
|
@group
|
|
(seq-filter (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
|
|
@result{} (1 3 5)
|
|
@end group
|
|
@group
|
|
(seq-filter (lambda (elt) (> elt 0)) '(-1 -3 -5))
|
|
@result{} nil
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-remove predicate sequence
|
|
@cindex removing from sequences
|
|
This function returns a list of all the elements in @var{sequence}
|
|
for which @var{predicate} returns @code{nil}.
|
|
|
|
@example
|
|
@group
|
|
(seq-remove (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
|
|
@result{} (-1 -3)
|
|
@end group
|
|
@group
|
|
(seq-remove (lambda (elt) (< elt 0)) '(-1 -3 -5))
|
|
@result{} nil
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-reduce function sequence initial-value
|
|
@cindex reducing sequences
|
|
This function returns the result of calling @var{function} with
|
|
@var{initial-value} and the first element of @var{sequence}, then calling
|
|
@var{function} with that result and the second element of @var{sequence},
|
|
then with that result and the third element of @var{sequence}, etc.
|
|
@var{function} should be a function of two arguments. If
|
|
@var{sequence} is empty, this returns @var{initial-value} without
|
|
calling @var{function}.
|
|
|
|
@example
|
|
@group
|
|
(seq-reduce #'+ [1 2 3 4] 0)
|
|
@result{} 10
|
|
@end group
|
|
@group
|
|
(seq-reduce #'+ '(1 2 3 4) 5)
|
|
@result{} 15
|
|
@end group
|
|
@group
|
|
(seq-reduce #'+ '() 3)
|
|
@result{} 3
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-some predicate sequence
|
|
This function returns the first non-@code{nil} value returned by
|
|
applying @var{predicate} to each element of @var{sequence} in turn.
|
|
|
|
@example
|
|
@group
|
|
(seq-some #'numberp ["abc" 1 nil])
|
|
@result{} t
|
|
@end group
|
|
@group
|
|
(seq-some #'numberp ["abc" "def"])
|
|
@result{} nil
|
|
@end group
|
|
@group
|
|
(seq-some #'null ["abc" 1 nil])
|
|
@result{} t
|
|
@end group
|
|
@group
|
|
(seq-some #'1+ [2 4 6])
|
|
@result{} 3
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-find predicate sequence &optional default
|
|
This function returns the first element for which @var{predicate}
|
|
returns non-@code{nil} in @var{sequence}. If no element matches
|
|
@var{predicate}, @var{default} is returned.
|
|
|
|
Note that this function has an ambiguity if the found element is
|
|
identical to @var{default}, as it cannot be known if an element was
|
|
found or not.
|
|
|
|
@example
|
|
@group
|
|
(seq-find #'numberp ["abc" 1 nil])
|
|
@result{} 1
|
|
@end group
|
|
@group
|
|
(seq-find #'numberp ["abc" "def"])
|
|
@result{} nil
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-every-p predicate sequence
|
|
This function returns non-@code{nil} if applying @var{predicate}
|
|
to every element of @var{sequence} returns non-@code{nil}.
|
|
|
|
@example
|
|
@group
|
|
(seq-every-p #'numberp [2 4 6])
|
|
@result{} t
|
|
@end group
|
|
@group
|
|
(seq-some #'numberp [2 4 "6"])
|
|
@result{} nil
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-empty-p sequence
|
|
This function returns non-@code{nil} if @var{sequence} is empty.
|
|
|
|
@example
|
|
@group
|
|
(seq-empty-p "not empty")
|
|
@result{} nil
|
|
@end group
|
|
@group
|
|
(seq-empty-p "")
|
|
@result{} t
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-count predicate sequence
|
|
This function returns the number of elements in @var{sequence} for which
|
|
@var{predicate} returns non-@code{nil}.
|
|
|
|
@example
|
|
(seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2])
|
|
@result{} 2
|
|
@end example
|
|
@end defun
|
|
|
|
@cindex sorting sequences
|
|
@defun seq-sort function sequence
|
|
This function returns a copy of @var{sequence} that is sorted
|
|
according to @var{function}, a function of two arguments that returns
|
|
non-@code{nil} if the first argument should sort before the second.
|
|
@end defun
|
|
|
|
@defun seq-contains sequence elt &optional function
|
|
This function returns the first element in @var{sequence} that is equal to
|
|
@var{elt}. If the optional argument @var{function} is non-@code{nil},
|
|
it is a function of two arguments to use instead of the default @code{equal}.
|
|
|
|
@example
|
|
@group
|
|
(seq-contains '(symbol1 symbol2) 'symbol1)
|
|
@result{} symbol1
|
|
@end group
|
|
@group
|
|
(seq-contains '(symbol1 symbol2) 'symbol3)
|
|
@result{} nil
|
|
@end group
|
|
@end example
|
|
|
|
@end defun
|
|
|
|
@defun seq-position sequence elt &optional function
|
|
This function returns the index of the first element in
|
|
@var{sequence} that is equal to @var{elt}. If the optional argument
|
|
@var{function} is non-@code{nil}, it is a function of two arguments to
|
|
use instead of the default @code{equal}.
|
|
|
|
@example
|
|
@group
|
|
(seq-position '(a b c) 'b)
|
|
@result{} 1
|
|
@end group
|
|
@group
|
|
(seq-position '(a b c) 'd)
|
|
@result{} nil
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
|
|
@defun seq-uniq sequence &optional function
|
|
This function returns a list of the elements of @var{sequence} with
|
|
duplicates removed. If the optional argument @var{function} is non-@code{nil},
|
|
it is a function of two arguments to use instead of the default @code{equal}.
|
|
|
|
@example
|
|
@group
|
|
(seq-uniq '(1 2 2 1 3))
|
|
@result{} (1 2 3)
|
|
@end group
|
|
@group
|
|
(seq-uniq '(1 2 2.0 1.0) #'=)
|
|
@result{} [3 4]
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-subseq sequence start &optional end
|
|
This function returns a subset of @var{sequence} from @var{start}
|
|
to @var{end}, both integers (@var{end} defaults to the last element).
|
|
If @var{start} or @var{end} is negative, it counts from the end of
|
|
@var{sequence}.
|
|
|
|
@example
|
|
@group
|
|
(seq-subseq '(1 2 3 4 5) 1)
|
|
@result{} (2 3 4 5)
|
|
@end group
|
|
@group
|
|
(seq-subseq '[1 2 3 4 5] 1 3)
|
|
@result{} [2 3]
|
|
@end group
|
|
@group
|
|
(seq-subseq '[1 2 3 4 5] -3 -1)
|
|
@result{} [3 4]
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-concatenate type &rest sequences
|
|
This function returns a sequence of type @var{type} made of the
|
|
concatenation of @var{sequences}. @var{type} may be: @code{vector},
|
|
@code{list} or @code{string}.
|
|
|
|
@example
|
|
@group
|
|
(seq-concatenate 'list '(1 2) '(3 4) [5 6])
|
|
@result{} (1 2 3 5 6)
|
|
@end group
|
|
@group
|
|
(seq-concatenate 'string "Hello " "world")
|
|
@result{} "Hello world"
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-mapcat function sequence &optional type
|
|
This function returns the result of applying @code{seq-concatenate}
|
|
to the result of applying @var{function} to each element of
|
|
@var{sequence}. The result is a sequence of type @var{type}, or a
|
|
list if @var{type} is @code{nil}.
|
|
|
|
@example
|
|
@group
|
|
(seq-mapcat #'seq-reverse '((3 2 1) (6 5 4)))
|
|
@result{} (1 2 3 4 5 6)
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-partition sequence n
|
|
This function returns a list of the elements of @var{sequence}
|
|
grouped into sub-sequences of length @var{n}. The last sequence may
|
|
contain less elements than @var{n}. @var{n} must be an integer. If
|
|
@var{n} is a negative integer or 0, nil is returned.
|
|
|
|
@example
|
|
@group
|
|
(seq-partition '(0 1 2 3 4 5 6 7) 3)
|
|
@result{} ((0 1 2) (3 4 5) (6 7))
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-intersection sequence1 sequence2 &optional function
|
|
This function returns a list of the elements that appear both in
|
|
@var{sequence1} and @var{sequence2}. If the optional argument
|
|
@var{function} is non-@code{nil}, it is a function of two arguments to
|
|
use to compare elements instead of the default @code{equal}.
|
|
|
|
@example
|
|
@group
|
|
(seq-intersection [2 3 4 5] [1 3 5 6 7])
|
|
@result{} (3 5)
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
|
|
@defun seq-difference sequence1 sequence2 &optional function
|
|
This function returns a list of the elements that appear in
|
|
@var{sequence1} but not in @var{sequence2}. If the optional argument
|
|
@var{function} is non-@code{nil}, it is a function of two arguments to
|
|
use to compare elements instead of the default @code{equal}.
|
|
|
|
@example
|
|
@group
|
|
(seq-difference '(2 3 4 5) [1 3 5 6 7])
|
|
@result{} (2 4)
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-group-by function sequence
|
|
This function separates the elements of @var{sequence} into an alist
|
|
whose keys are the result of applying @var{function} to each element
|
|
of @var{sequence}. Keys are compared using @code{equal}.
|
|
|
|
@example
|
|
@group
|
|
(seq-group-by #'integerp '(1 2.1 3 2 3.2))
|
|
@result{} ((t 1 3 2) (nil 2.1 3.2))
|
|
@end group
|
|
@group
|
|
(seq-group-by #'car '((a 1) (b 2) (a 3) (c 4)))
|
|
@result{} ((b (b 2)) (a (a 1) (a 3)) (c (c 4)))
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-into sequence type
|
|
This function converts the sequence @var{sequence} into a sequence
|
|
of type @var{type}. @var{type} can be one of the following symbols:
|
|
@code{vector}, @code{string} or @code{list}.
|
|
|
|
@example
|
|
@group
|
|
(seq-into [1 2 3] 'list)
|
|
@result{} (1 2 3)
|
|
@end group
|
|
@group
|
|
(seq-into nil 'vector)
|
|
@result{} []
|
|
@end group
|
|
@group
|
|
(seq-into "hello" 'vector)
|
|
@result{} [104 101 108 108 111]
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-min sequence
|
|
This function returns the smallest element of
|
|
@var{sequence}. @var{sequence} must be a sequence of numbers or
|
|
markers.
|
|
|
|
@example
|
|
@group
|
|
(seq-min [3 1 2])
|
|
@result{} 1
|
|
@end group
|
|
@group
|
|
(seq-min "Hello")
|
|
@result{} 72
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun seq-max sequence
|
|
This function returns the largest element of
|
|
@var{sequence}. @var{sequence} must be a sequence of numbers or
|
|
markers.
|
|
|
|
@example
|
|
@group
|
|
(seq-max [1 3 2])
|
|
@result{} 3
|
|
@end group
|
|
@group
|
|
(seq-max "Hello")
|
|
@result{} 111
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defmac seq-doseq (var sequence) body@dots{}
|
|
@cindex sequence iteration
|
|
This macro is like @code{dolist}, except that @var{sequence} can be a list,
|
|
vector or string (@pxref{Iteration} for more information about the
|
|
@code{dolist} macro). This is primarily useful for side-effects.
|
|
@end defmac
|
|
|
|
@defmac seq-let arguments sequence body@dots{}
|
|
@cindex sequence destructuring
|
|
This macro binds the variables defined in @var{arguments} to the
|
|
elements of the sequence @var{sequence}. @var{arguments} can itself
|
|
include sequences allowing for nested destructuring.
|
|
|
|
The @var{arguments} sequence can also include the @code{&rest} marker
|
|
followed by a variable name to be bound to the rest of
|
|
@code{sequence}.
|
|
|
|
@example
|
|
@group
|
|
(seq-let [first second] [1 2 3 4]
|
|
(list first second))
|
|
@result{} (1 2)
|
|
@end group
|
|
@group
|
|
(seq-let (_ a _ b) '(1 2 3 4)
|
|
(list a b))
|
|
@result{} (2 4)
|
|
@end group
|
|
@group
|
|
(seq-let [a [b [c]]] [1 [2 [3]]]
|
|
(list a b c))
|
|
@result{} (1 2 3)
|
|
@end group
|
|
@group
|
|
(seq-let [a b &rest others] [1 2 3 4]
|
|
others)
|
|
@end group
|
|
@result{} [3 4]
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@node Arrays
|
|
@section Arrays
|
|
@cindex array
|
|
|
|
An @dfn{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:
|
|
@dfn{strings} (@pxref{String Type}), @dfn{vectors} (@pxref{Vector
|
|
Type}), @dfn{bool-vectors} (@pxref{Bool-Vector Type}), and
|
|
@dfn{char-tables} (@pxref{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 @code{t} and @code{nil}.
|
|
|
|
All four kinds of array share these characteristics:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The first element of an array has index zero, the second element has
|
|
index 1, and so on. This is called @dfn{zero-origin} indexing. For
|
|
example, an array of four elements has indices 0, 1, 2, @w{and 3}.
|
|
|
|
@item
|
|
The length of the array is fixed once you create it; you cannot
|
|
change the length of an existing array.
|
|
|
|
@item
|
|
For purposes of evaluation, the array is a constant---i.e.,
|
|
it evaluates to itself.
|
|
|
|
@item
|
|
The elements of an array may be referenced or changed with the functions
|
|
@code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
|
|
@end itemize
|
|
|
|
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:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
They occupy one-fourth the space of a vector of the same elements.
|
|
|
|
@item
|
|
Strings are printed in a way that shows the contents more clearly
|
|
as text.
|
|
|
|
@item
|
|
Strings can hold text properties. @xref{Text Properties}.
|
|
|
|
@item
|
|
Many of the specialized editing and I/O facilities of Emacs accept only
|
|
strings. For example, you cannot insert a vector of characters into a
|
|
buffer the way you can insert a string. @xref{Strings and Characters}.
|
|
@end itemize
|
|
|
|
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. @xref{Key
|
|
Sequence Input}.
|
|
|
|
@node Array Functions
|
|
@section Functions that Operate on Arrays
|
|
|
|
In this section, we describe the functions that accept all types of
|
|
arrays.
|
|
|
|
@defun arrayp object
|
|
This function returns @code{t} if @var{object} is an array (i.e., a
|
|
vector, a string, a bool-vector or a char-table).
|
|
|
|
@example
|
|
@group
|
|
(arrayp [a])
|
|
@result{} t
|
|
(arrayp "asdf")
|
|
@result{} t
|
|
(arrayp (syntax-table)) ;; @r{A char-table.}
|
|
@result{} t
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun aref array index
|
|
@cindex array elements
|
|
This function returns the @var{index}th element of @var{array}. The
|
|
first element is at index zero.
|
|
|
|
@example
|
|
@group
|
|
(setq primes [2 3 5 7 11 13])
|
|
@result{} [2 3 5 7 11 13]
|
|
(aref primes 4)
|
|
@result{} 11
|
|
@end group
|
|
@group
|
|
(aref "abcdefg" 1)
|
|
@result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.}
|
|
@end group
|
|
@end example
|
|
|
|
See also the function @code{elt}, in @ref{Sequence Functions}.
|
|
@end defun
|
|
|
|
@defun aset array index object
|
|
This function sets the @var{index}th element of @var{array} to be
|
|
@var{object}. It returns @var{object}.
|
|
|
|
@example
|
|
@group
|
|
(setq w [foo bar baz])
|
|
@result{} [foo bar baz]
|
|
(aset w 0 'fu)
|
|
@result{} fu
|
|
w
|
|
@result{} [fu bar baz]
|
|
@end group
|
|
|
|
@group
|
|
(setq x "asdfasfd")
|
|
@result{} "asdfasfd"
|
|
(aset x 3 ?Z)
|
|
@result{} 90
|
|
x
|
|
@result{} "asdZasfd"
|
|
@end group
|
|
@end example
|
|
|
|
If @var{array} is a string and @var{object} is not a character, a
|
|
@code{wrong-type-argument} error results. The function converts a
|
|
unibyte string to multibyte if necessary to insert a character.
|
|
@end defun
|
|
|
|
@defun fillarray array object
|
|
This function fills the array @var{array} with @var{object}, so that
|
|
each element of @var{array} is @var{object}. It returns @var{array}.
|
|
|
|
@example
|
|
@group
|
|
(setq a [a b c d e f g])
|
|
@result{} [a b c d e f g]
|
|
(fillarray a 0)
|
|
@result{} [0 0 0 0 0 0 0]
|
|
a
|
|
@result{} [0 0 0 0 0 0 0]
|
|
@end group
|
|
@group
|
|
(setq s "When in the course")
|
|
@result{} "When in the course"
|
|
(fillarray s ?-)
|
|
@result{} "------------------"
|
|
@end group
|
|
@end example
|
|
|
|
If @var{array} is a string and @var{object} is not a character, a
|
|
@code{wrong-type-argument} error results.
|
|
@end defun
|
|
|
|
The general sequence functions @code{copy-sequence} and @code{length}
|
|
are often useful for objects known to be arrays. @xref{Sequence Functions}.
|
|
|
|
@node Vectors
|
|
@section Vectors
|
|
@cindex vector (type)
|
|
|
|
A @dfn{vector} is a general-purpose array whose elements can be any
|
|
Lisp objects. (By contrast, the elements of a string can only be
|
|
characters. @xref{Strings and Characters}.) Vectors are used in
|
|
Emacs for many purposes: as key sequences (@pxref{Key Sequences}), as
|
|
symbol-lookup tables (@pxref{Creating Symbols}), as part of the
|
|
representation of a byte-compiled function (@pxref{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 @code{a}, @code{b} and
|
|
@code{a} is printed as @code{[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.
|
|
@xref{Self-Evaluating Forms}.
|
|
|
|
Here are examples illustrating these principles:
|
|
|
|
@example
|
|
@group
|
|
(setq avector [1 two '(three) "four" [five]])
|
|
@result{} [1 two (quote (three)) "four" [five]]
|
|
(eval avector)
|
|
@result{} [1 two (quote (three)) "four" [five]]
|
|
(eq avector (eval avector))
|
|
@result{} t
|
|
@end group
|
|
@end example
|
|
|
|
@node Vector Functions
|
|
@section Functions for Vectors
|
|
|
|
Here are some functions that relate to vectors:
|
|
|
|
@defun vectorp object
|
|
This function returns @code{t} if @var{object} is a vector.
|
|
|
|
@example
|
|
@group
|
|
(vectorp [a])
|
|
@result{} t
|
|
(vectorp "asdf")
|
|
@result{} nil
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun vector &rest objects
|
|
This function creates and returns a vector whose elements are the
|
|
arguments, @var{objects}.
|
|
|
|
@example
|
|
@group
|
|
(vector 'foo 23 [bar baz] "rats")
|
|
@result{} [foo 23 [bar baz] "rats"]
|
|
(vector)
|
|
@result{} []
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun make-vector length object
|
|
This function returns a new vector consisting of @var{length} elements,
|
|
each initialized to @var{object}.
|
|
|
|
@example
|
|
@group
|
|
(setq sleepy (make-vector 9 'Z))
|
|
@result{} [Z Z Z Z Z Z Z Z Z]
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun vconcat &rest sequences
|
|
@cindex copying vectors
|
|
This function returns a new vector containing all the elements of
|
|
@var{sequences}. The arguments @var{sequences} may be true lists,
|
|
vectors, strings or bool-vectors. If no @var{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 @code{eq} to any existing vector.
|
|
|
|
@example
|
|
@group
|
|
(setq a (vconcat '(A B C) '(D E F)))
|
|
@result{} [A B C D E F]
|
|
(eq a (vconcat a))
|
|
@result{} nil
|
|
@end group
|
|
@group
|
|
(vconcat)
|
|
@result{} []
|
|
(vconcat [A B C] "aa" '(foo (6 7)))
|
|
@result{} [A B C 97 97 foo (6 7)]
|
|
@end group
|
|
@end example
|
|
|
|
The @code{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. @xref{Byte-Code Objects}.
|
|
|
|
For other concatenation functions, see @code{mapconcat} in @ref{Mapping
|
|
Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
|
|
in @ref{Building Lists}.
|
|
@end defun
|
|
|
|
The @code{append} function also provides a way to convert a vector into a
|
|
list with the same elements:
|
|
|
|
@example
|
|
@group
|
|
(setq avector [1 two (quote (three)) "four" [five]])
|
|
@result{} [1 two (quote (three)) "four" [five]]
|
|
(append avector nil)
|
|
@result{} (1 two (quote (three)) "four" [five])
|
|
@end group
|
|
@end example
|
|
|
|
@node Char-Tables
|
|
@section Char-Tables
|
|
@cindex char-tables
|
|
@cindex extra slots of char-table
|
|
|
|
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 @code{aref} and @code{aset}, as with any array. In
|
|
addition, a char-table can have @dfn{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.
|
|
|
|
@cindex subtype of char-table
|
|
Each char-table has a @dfn{subtype}, a symbol, which serves two
|
|
purposes:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The subtype provides an easy way to tell what the char-table is for.
|
|
For instance, display tables are char-tables with @code{display-table}
|
|
as the subtype, and syntax tables are char-tables with
|
|
@code{syntax-table} as the subtype. The subtype can be queried using
|
|
the function @code{char-table-subtype}, described below.
|
|
|
|
@item
|
|
The subtype controls the number of @dfn{extra slots} in the
|
|
char-table. This number is specified by the subtype's
|
|
@code{char-table-extra-slots} symbol property (@pxref{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.
|
|
@end itemize
|
|
|
|
@cindex parent of char-table
|
|
A char-table can have a @dfn{parent}, which is another char-table. If
|
|
it does, then whenever the char-table specifies @code{nil} for a
|
|
particular character @var{c}, it inherits the value specified in the
|
|
parent. In other words, @code{(aref @var{char-table} @var{c})} returns
|
|
the value from the parent of @var{char-table} if @var{char-table} itself
|
|
specifies @code{nil}.
|
|
|
|
@cindex default value of char-table
|
|
A char-table can also have a @dfn{default value}. If so, then
|
|
@code{(aref @var{char-table} @var{c})} returns the default value
|
|
whenever the char-table does not specify any other non-@code{nil} value.
|
|
|
|
@defun make-char-table subtype &optional init
|
|
Return a newly-created char-table, with subtype @var{subtype} (a
|
|
symbol). Each element is initialized to @var{init}, which defaults to
|
|
@code{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 @var{subtype} has the @code{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,
|
|
@code{make-char-table} raises an error. If @var{subtype} has no
|
|
@code{char-table-extra-slots} symbol property (@pxref{Property
|
|
Lists}), the char-table has no extra slots.
|
|
@end defun
|
|
|
|
@defun char-table-p object
|
|
This function returns @code{t} if @var{object} is a char-table, and
|
|
@code{nil} otherwise.
|
|
@end defun
|
|
|
|
@defun char-table-subtype char-table
|
|
This function returns the subtype symbol of @var{char-table}.
|
|
@end defun
|
|
|
|
There is no special function to access default values in a char-table.
|
|
To do that, use @code{char-table-range} (see below).
|
|
|
|
@defun char-table-parent char-table
|
|
This function returns the parent of @var{char-table}. The parent is
|
|
always either @code{nil} or another char-table.
|
|
@end defun
|
|
|
|
@defun set-char-table-parent char-table new-parent
|
|
This function sets the parent of @var{char-table} to @var{new-parent}.
|
|
@end defun
|
|
|
|
@defun char-table-extra-slot char-table n
|
|
This function returns the contents of extra slot @var{n} (zero based)
|
|
of @var{char-table}. The number of extra slots in a char-table is
|
|
determined by its subtype.
|
|
@end defun
|
|
|
|
@defun set-char-table-extra-slot char-table n value
|
|
This function stores @var{value} in extra slot @var{n} (zero based) of
|
|
@var{char-table}.
|
|
@end defun
|
|
|
|
A char-table can specify an element value for a single character code;
|
|
it can also specify a value for an entire character set.
|
|
|
|
@defun char-table-range char-table range
|
|
This returns the value specified in @var{char-table} for a range of
|
|
characters @var{range}. Here are the possibilities for @var{range}:
|
|
|
|
@table @asis
|
|
@item @code{nil}
|
|
Refers to the default value.
|
|
|
|
@item @var{char}
|
|
Refers to the element for character @var{char}
|
|
(supposing @var{char} is a valid character code).
|
|
|
|
@item @code{(@var{from} . @var{to})}
|
|
A cons cell refers to all the characters in the inclusive range
|
|
@samp{[@var{from}..@var{to}]}.
|
|
@end table
|
|
@end defun
|
|
|
|
@defun set-char-table-range char-table range value
|
|
This function sets the value in @var{char-table} for a range of
|
|
characters @var{range}. Here are the possibilities for @var{range}:
|
|
|
|
@table @asis
|
|
@item @code{nil}
|
|
Refers to the default value.
|
|
|
|
@item @code{t}
|
|
Refers to the whole range of character codes.
|
|
|
|
@item @var{char}
|
|
Refers to the element for character @var{char}
|
|
(supposing @var{char} is a valid character code).
|
|
|
|
@item @code{(@var{from} . @var{to})}
|
|
A cons cell refers to all the characters in the inclusive range
|
|
@samp{[@var{from}..@var{to}]}.
|
|
@end table
|
|
@end defun
|
|
|
|
@defun map-char-table function char-table
|
|
This function calls its argument @var{function} for each element of
|
|
@var{char-table} that has a non-@code{nil} value. The call to
|
|
@var{function} is with two arguments, a key and a value. The key
|
|
is a possible @var{range} argument for @code{char-table-range}---either
|
|
a valid character or a cons cell @code{(@var{from} . @var{to})},
|
|
specifying a range of characters that share the same value. The value is
|
|
what @code{(char-table-range @var{char-table} @var{key})} returns.
|
|
|
|
Overall, the key-value pairs passed to @var{function} describe all the
|
|
values stored in @var{char-table}.
|
|
|
|
The return value is always @code{nil}; to make calls to
|
|
@code{map-char-table} useful, @var{function} should have side effects.
|
|
For example, here is how to examine the elements of the syntax table:
|
|
|
|
@example
|
|
(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)
|
|
@result{}
|
|
(((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)))
|
|
@end example
|
|
@end defun
|
|
|
|
@node Bool-Vectors
|
|
@section Bool-vectors
|
|
@cindex Bool-vectors
|
|
|
|
A bool-vector is much like a vector, except that it stores only the
|
|
values @code{t} and @code{nil}. If you try to store any non-@code{nil}
|
|
value into an element of the bool-vector, the effect is to store
|
|
@code{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.
|
|
|
|
@defun make-bool-vector length initial
|
|
Return a new bool-vector of @var{length} elements,
|
|
each one initialized to @var{initial}.
|
|
@end defun
|
|
|
|
@defun bool-vector &rest objects
|
|
This function creates and returns a bool-vector whose elements are the
|
|
arguments, @var{objects}.
|
|
@end defun
|
|
|
|
@defun bool-vector-p object
|
|
This returns @code{t} if @var{object} is a bool-vector,
|
|
and @code{nil} otherwise.
|
|
@end defun
|
|
|
|
There are also some bool-vector set operation functions, described below:
|
|
|
|
@defun bool-vector-exclusive-or a b &optional c
|
|
Return @dfn{bitwise exclusive or} of bool vectors @var{a} and @var{b}.
|
|
If optional argument @var{c} is given, the result of this operation is
|
|
stored into @var{c}. All arguments should be bool vectors of the same length.
|
|
@end defun
|
|
|
|
@defun bool-vector-union a b &optional c
|
|
Return @dfn{bitwise or} of bool vectors @var{a} and @var{b}. If
|
|
optional argument @var{c} is given, the result of this operation is
|
|
stored into @var{c}. All arguments should be bool vectors of the same length.
|
|
@end defun
|
|
|
|
@defun bool-vector-intersection a b &optional c
|
|
Return @dfn{bitwise and} of bool vectors @var{a} and @var{b}. If
|
|
optional argument @var{c} is given, the result of this operation is
|
|
stored into @var{c}. All arguments should be bool vectors of the same length.
|
|
@end defun
|
|
|
|
@defun bool-vector-set-difference a b &optional c
|
|
Return @dfn{set difference} of bool vectors @var{a} and @var{b}. If
|
|
optional argument @var{c} is given, the result of this operation is
|
|
stored into @var{c}. All arguments should be bool vectors of the same length.
|
|
@end defun
|
|
|
|
@defun bool-vector-not a &optional b
|
|
Return @dfn{set complement} of bool vector @var{a}. If optional
|
|
argument @var{b} is given, the result of this operation is stored into
|
|
@var{b}. All arguments should be bool vectors of the same length.
|
|
@end defun
|
|
|
|
@defun bool-vector-subsetp a b
|
|
Return @code{t} if every @code{t} value in @var{a} is also t in
|
|
@var{b}, @code{nil} otherwise. All arguments should be bool vectors of the
|
|
same length.
|
|
@end defun
|
|
|
|
@defun bool-vector-count-consecutive a b i
|
|
Return the number of consecutive elements in @var{a} equal @var{b}
|
|
starting at @var{i}. @code{a} is a bool vector, @var{b} is @code{t}
|
|
or @code{nil}, and @var{i} is an index into @code{a}.
|
|
@end defun
|
|
|
|
@defun bool-vector-count-population a
|
|
Return the number of elements that are @code{t} in bool vector @var{a}.
|
|
@end defun
|
|
|
|
The printed form represents up to 8 boolean values as a single
|
|
character:
|
|
|
|
@example
|
|
@group
|
|
(bool-vector t nil t nil)
|
|
@result{} #&4"^E"
|
|
(bool-vector)
|
|
@result{} #&0""
|
|
@end group
|
|
@end example
|
|
|
|
You can use @code{vconcat} to print a bool-vector like other vectors:
|
|
|
|
@example
|
|
@group
|
|
(vconcat (bool-vector nil t nil t))
|
|
@result{} [nil t nil t]
|
|
@end group
|
|
@end example
|
|
|
|
Here is another example of creating, examining, and updating a
|
|
bool-vector:
|
|
|
|
@example
|
|
(setq bv (make-bool-vector 5 t))
|
|
@result{} #&5"^_"
|
|
(aref bv 1)
|
|
@result{} t
|
|
(aset bv 3 nil)
|
|
@result{} nil
|
|
bv
|
|
@result{} #&5"^W"
|
|
@end example
|
|
|
|
@noindent
|
|
These results make sense because the binary codes for control-_ and
|
|
control-W are 11111 and 10111, respectively.
|
|
|
|
@node Rings
|
|
@section Managing a Fixed-Size Ring of Objects
|
|
|
|
@cindex ring data structure
|
|
A @dfn{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 @code{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, @emph{not} using
|
|
the @code{ring} package; thus the following functions won't work on
|
|
them.
|
|
|
|
@defun make-ring size
|
|
This returns a new ring capable of holding @var{size} objects.
|
|
@var{size} should be an integer.
|
|
@end defun
|
|
|
|
@defun ring-p object
|
|
This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
|
|
@end defun
|
|
|
|
@defun ring-size ring
|
|
This returns the maximum capacity of the @var{ring}.
|
|
@end defun
|
|
|
|
@defun ring-length ring
|
|
This returns the number of objects that @var{ring} currently contains.
|
|
The value will never exceed that returned by @code{ring-size}.
|
|
@end defun
|
|
|
|
@defun ring-elements ring
|
|
This returns a list of the objects in @var{ring}, in order, newest first.
|
|
@end defun
|
|
|
|
@defun ring-copy ring
|
|
This returns a new ring which is a copy of @var{ring}.
|
|
The new ring contains the same (@code{eq}) objects as @var{ring}.
|
|
@end defun
|
|
|
|
@defun ring-empty-p ring
|
|
This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
|
|
@end defun
|
|
|
|
The newest element in the ring always has index 0. Higher indices
|
|
correspond to older elements. Indices are computed modulo the ring
|
|
length. Index @minus{}1 corresponds to the oldest element, @minus{}2
|
|
to the next-oldest, and so forth.
|
|
|
|
@defun ring-ref ring index
|
|
This returns the object in @var{ring} found at index @var{index}.
|
|
@var{index} may be negative or greater than the ring length. If
|
|
@var{ring} is empty, @code{ring-ref} signals an error.
|
|
@end defun
|
|
|
|
@defun ring-insert ring object
|
|
This inserts @var{object} into @var{ring}, making it the newest
|
|
element, and returns @var{object}.
|
|
|
|
If the ring is full, insertion removes the oldest element to
|
|
make room for the new element.
|
|
@end defun
|
|
|
|
@defun ring-remove ring &optional index
|
|
Remove an object from @var{ring}, and return that object. The
|
|
argument @var{index} specifies which item to remove; if it is
|
|
@code{nil}, that means to remove the oldest item. If @var{ring} is
|
|
empty, @code{ring-remove} signals an error.
|
|
@end defun
|
|
|
|
@defun ring-insert-at-beginning ring object
|
|
This inserts @var{object} into @var{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.
|
|
@end defun
|
|
|
|
@cindex fifo data structure
|
|
If you are careful not to exceed the ring size, you can
|
|
use the ring as a first-in-first-out queue. For example:
|
|
|
|
@lisp
|
|
(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)))
|
|
@result{} (0 t one t "two")
|
|
@end lisp
|