annotate lispref/sequences.texi @ 13652:0923c642e324

Exclude subdirs.el.
author Richard M. Stallman <rms@gnu.org>
date Sat, 25 Nov 1995 05:49:37 +0000
parents a6eb5f12b0f3
children 66d807bdc5b4
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4 @c See the file elisp.texi for copying conditions.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @setfilename ../info/sequences
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @node Sequences Arrays Vectors, Symbols, Lists, Top
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @chapter Sequences, Arrays, and Vectors
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @cindex sequence
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 Recall that the @dfn{sequence} type is the union of three other Lisp
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 types: lists, vectors, and strings. In other words, any list is a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 sequence, any vector is a sequence, and any string is a sequence. The
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 common property that all sequences have is that each is an ordered
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 collection of elements.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
16 An @dfn{array} is a single primitive object that has a slot for each
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
17 elements. All the elements are accessible in constant time, but the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
18 length of an existing array cannot be changed. Strings and vectors are
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
19 the two types of arrays.
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
20
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
21 A list is a sequence of elements, but it is not a single primitive
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
22 object; it is made of cons cells, one cell per element. Finding the
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
23 @var{n}th element requires looking through @var{n} cons cells, so
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
24 elements farther from the beginning of the list take longer to access.
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
25 But it is possible to add elements to the list, or remove elements.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 The following diagram shows the relationship between these types:
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @group
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
31 ___________________________________
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
32 | |
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
33 | Sequence |
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
34 | ______ ______________________ |
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
35 | | | | | |
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
36 | | List | | Array | |
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
37 | | | | ________ _______ | |
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
38 | |______| | | | | | | |
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
39 | | | Vector | | String| | |
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
40 | | |________| |_______| | |
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
41 | |______________________| |
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
42 |___________________________________|
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 The elements of vectors and lists may be any Lisp objects. The
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 elements of strings are all characters.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 @menu
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 * Sequence Functions:: Functions that accept any kind of sequence.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 * Arrays:: Characteristics of arrays in Emacs Lisp.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 * Array Functions:: Functions specifically for arrays.
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
53 * Vectors:: Special characteristics of Emacs Lisp vectors.
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
54 * Vector Functions:: Functions specifically for vectors.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 @end menu
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 @node Sequence Functions
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 @section Sequences
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 string. The common property that all sequences have is that each is an
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 ordered collection of elements. This section describes functions that
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 accept any kind of sequence.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 @defun sequencep object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 Returns @code{t} if @var{object} is a list, vector, or
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 string, @code{nil} otherwise.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 @defun copy-sequence sequence
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 @cindex copying sequences
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 Returns a copy of @var{sequence}. The copy is the same type of object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 as the original sequence, and it has the same elements in the same order.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 Storing a new element into the copy does not affect the original
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 @var{sequence}, and vice versa. However, the elements of the new
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 sequence are not copies; they are identical (@code{eq}) to the elements
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 of the original. Therefore, changes made within these elements, as
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 found via the copied sequence, are also visible in the original
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 sequence.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 If the sequence is a string with text properties, the property list in
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 the copy is itself a copy, not shared with the original's property
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 list. However, the actual values of the properties are shared.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 @xref{Text Properties}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 See also @code{append} in @ref{Building Lists}, @code{concat} in
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 @ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for others
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 ways to copy sequences.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 (setq bar '(1 2))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 @result{} (1 2)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 (setq x (vector 'foo bar))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 @result{} [foo (1 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 (setq y (copy-sequence x))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 @result{} [foo (1 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 (eq x y)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 @result{} nil
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 (equal x y)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 (eq (elt x 1) (elt y 1))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 ;; @r{Replacing an element of one sequence.}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 (aset x 0 'quux)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 x @result{} [quux (1 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 y @result{} [foo (1 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 ;; @r{Modifying the inside of a shared element.}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 (setcar (aref x 1) 69)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 x @result{} [quux (69 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 y @result{} [foo (69 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 @defun length sequence
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 @cindex string length
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @cindex list length
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 @cindex vector length
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 @cindex sequence length
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 Returns the number of elements in @var{sequence}. If @var{sequence} is
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 a cons cell that is not a list (because the final @sc{cdr} is not
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 @code{nil}), a @code{wrong-type-argument} error is signaled.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 (length '(1 2 3))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 @result{} 3
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 (length ())
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 @result{} 0
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 (length "foobar")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 @result{} 6
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 (length [1 2 3])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @result{} 3
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 @defun elt sequence index
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @cindex elements of sequences
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 This function returns the element of @var{sequence} indexed by
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 @var{index}. Legitimate values of @var{index} are integers ranging from
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 0 up to one less than the length of @var{sequence}. If @var{sequence}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 is a list, then out-of-range values of @var{index} return @code{nil};
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 otherwise, they trigger an @code{args-out-of-range} error.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 (elt [1 2 3 4] 2)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @result{} 3
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 (elt '(1 2 3 4) 2)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @result{} 3
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 (char-to-string (elt "1234" 2))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @result{} "3"
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 (elt [1 2 3 4] 4)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @error{}Args out of range: [1 2 3 4], 4
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 (elt [1 2 3 4] -1)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @error{}Args out of range: [1 2 3 4], -1
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
194 This function generalizes @code{aref} (@pxref{Array Functions}) and
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
195 @code{nth} (@pxref{List Elements}).
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 @node Arrays
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 @section Arrays
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 @cindex array
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
202 An @dfn{array} object has slots that hold a number of other Lisp
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 objects, called the elements of the array. Any element of an array may
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 be accessed in constant time. In contrast, an element of a list
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 requires access time that is proportional to the position of the element
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 in the list.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 When you create an array, you must specify how many elements it has.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 The amount of space allocated depends on the number of elements.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 Therefore, it is impossible to change the size of an array once it is
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
211 created; you cannot add or remove elements. However, you can replace an
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
212 element with a different value.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 Emacs defines two types of array, both of which are one-dimensional:
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 @dfn{strings} and @dfn{vectors}. A vector is a general array; its
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 elements can be any Lisp objects. A string is a specialized array; its
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 elements must be characters (i.e., integers between 0 and 255). Each
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 type of array has its own read syntax. @xref{String Type}, and
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @ref{Vector Type}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
221 Both kinds of array share these characteristics:
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @itemize @bullet
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 The first element of an array has index zero, the second element has
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 index 1, and so on. This is called @dfn{zero-origin} indexing. For
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 example, an array of four elements has indices 0, 1, 2, @w{and 3}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 The elements of an array may be referenced or changed with the functions
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 @code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 @end itemize
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
234 In principle, if you wish to have an array of text characters, you
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
235 could use either a string or a vector. In practice, we always choose
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
236 strings for such applications, for four reasons:
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 @itemize @bullet
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 They occupy one-fourth the space of a vector of the same elements.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 Strings are printed in a way that shows the contents more clearly
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 as characters.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 Strings can hold text properties. @xref{Text Properties}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 Many of the specialized editing and I/O facilities of Emacs accept only
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 strings. For example, you cannot insert a vector of characters into a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 buffer the way you can insert a string. @xref{Strings and Characters}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 @end itemize
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
255 By contrast, for an array of keyboard input characters (such as a key
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
256 sequence), a vector may be necessary, because many keyboard input
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
257 characters are outside the range that will fit in a string. @xref{Key
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
258 Sequence Input}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
259
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 @node Array Functions
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @section Functions that Operate on Arrays
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 In this section, we describe the functions that accept both strings
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 and vectors.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 @defun arrayp object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 This function returns @code{t} if @var{object} is an array (i.e., either a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 vector or a string).
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 (arrayp [a])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 (arrayp "asdf")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 @defun aref array index
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @cindex array elements
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 This function returns the @var{index}th element of @var{array}. The
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 first element is at index zero.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 (setq primes [2 3 5 7 11 13])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 @result{} [2 3 5 7 11 13]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 (aref primes 4)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @result{} 11
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 (elt primes 4)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @result{} 11
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 (aref "abcdefg" 1)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 @result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 See also the function @code{elt}, in @ref{Sequence Functions}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @defun aset array index object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 This function sets the @var{index}th element of @var{array} to be
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 @var{object}. It returns @var{object}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 (setq w [foo bar baz])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @result{} [foo bar baz]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 (aset w 0 'fu)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 @result{} fu
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 w
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @result{} [fu bar baz]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 (setq x "asdfasfd")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 @result{} "asdfasfd"
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 (aset x 3 ?Z)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 @result{} 90
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 x
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 @result{} "asdZasfd"
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 If @var{array} is a string and @var{object} is not a character, a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 @code{wrong-type-argument} error results.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 @defun fillarray array object
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
333 This function fills the array @var{array} with @var{object}, so that
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
334 each element of @var{array} is @var{object}. It returns @var{array}.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 (setq a [a b c d e f g])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 @result{} [a b c d e f g]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 (fillarray a 0)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @result{} [0 0 0 0 0 0 0]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @result{} [0 0 0 0 0 0 0]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 (setq s "When in the course")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 @result{} "When in the course"
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 (fillarray s ?-)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 @result{} "------------------"
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 If @var{array} is a string and @var{object} is not a character, a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @code{wrong-type-argument} error results.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 The general sequence functions @code{copy-sequence} and @code{length}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 are often useful for objects known to be arrays. @xref{Sequence Functions}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 @node Vectors
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 @section Vectors
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 @cindex vector
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 Arrays in Lisp, like arrays in most languages, are blocks of memory
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 whose elements can be accessed in constant time. A @dfn{vector} is a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 general-purpose array; its elements can be any Lisp objects. (The other
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 kind of array in Emacs Lisp is the @dfn{string}, whose elements must be
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 characters.) Vectors in Emacs serve as syntax tables (vectors of
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 integers), as obarrays (vectors of symbols), and in keymaps (vectors of
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 commands). They are also used internally as part of the representation
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 of a byte-compiled function; if you print such a function, you will see
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 a vector in it.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 In Emacs Lisp, the indices of the elements of a vector start from zero
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 and count up from there.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
377 Vectors are printed with square brackets surrounding the elements.
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
378 Thus, a vector whose elements are the symbols @code{a}, @code{b} and
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
379 @code{a} is printed as @code{[a b a]}. You can write vectors in the
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
380 same way in Lisp input.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 A vector, like a string or a number, is considered a constant for
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 evaluation: the result of evaluating it is the same vector. This does
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 not evaluate or even examine the elements of the vector.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 @xref{Self-Evaluating Forms}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 Here are examples of these principles:
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 (setq avector [1 two '(three) "four" [five]])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @result{} [1 two (quote (three)) "four" [five]]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 (eval avector)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 @result{} [1 two (quote (three)) "four" [five]]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 (eq avector (eval avector))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
400 @node Vector Functions
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
401 @section Functions That Operate on Vectors
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
402
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 Here are some functions that relate to vectors:
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 @defun vectorp object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 This function returns @code{t} if @var{object} is a vector.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 (vectorp [a])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 (vectorp "asdf")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 @result{} nil
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 @defun vector &rest objects
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 This function creates and returns a vector whose elements are the
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 arguments, @var{objects}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 (vector 'foo 23 [bar baz] "rats")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 @result{} [foo 23 [bar baz] "rats"]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 (vector)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @result{} []
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 @defun make-vector length object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 This function returns a new vector consisting of @var{length} elements,
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 each initialized to @var{object}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 (setq sleepy (make-vector 9 'Z))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 @result{} [Z Z Z Z Z Z Z Z Z]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @defun vconcat &rest sequences
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 @cindex copying vectors
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 This function returns a new vector containing all the elements of the
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @var{sequences}. The arguments @var{sequences} may be lists, vectors,
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 or strings. If no @var{sequences} are given, an empty vector is
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 returned.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 The value is a newly constructed vector that is not @code{eq} to any
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 existing vector.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 (setq a (vconcat '(A B C) '(D E F)))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @result{} [A B C D E F]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 (eq a (vconcat a))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 @result{} nil
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 (vconcat)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 @result{} []
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 (vconcat [A B C] "aa" '(foo (6 7)))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @result{} [A B C 97 97 foo (6 7)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7119
diff changeset
469 The @code{vconcat} function also allows integers as arguments. It
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7119
diff changeset
470 converts them to strings of digits, making up the decimal print
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7119
diff changeset
471 representation of the integer, and then uses the strings instead of the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7119
diff changeset
472 original integers. @strong{Don't use this feature; we plan to eliminate
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7119
diff changeset
473 it. If you already use this feature, change your programs now!} The
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7119
diff changeset
474 proper way to convert an integer to a decimal number in this way is with
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 @code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 (@pxref{String Conversion}).
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 For other concatenation functions, see @code{mapconcat} in @ref{Mapping
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 in @ref{Building Lists}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 The @code{append} function provides a way to convert a vector into a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 list with the same elements (@pxref{Building Lists}):
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 (setq avector [1 two (quote (three)) "four" [five]])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @result{} [1 two (quote (three)) "four" [five]]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 (append avector nil)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @result{} (1 two (quote (three)) "four" [five])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 @end example